Update contributing reference based on split uv/pip flows

content/contributing/index.md

@@ -14,13 +14,14 @@ these guides:
 
 If you would like to fix an issue or implement a feature, see these guides:
 
--   [Quick Reference](quick.md) If you're already familiar with contributing,
+-   [Quick Reference](quick.md): If you're already familiar with contributing,
     this provides an essential overview of the following guides.
--   Start Here: Detailed Development Environment Setup - Coming Soon
+-   [Detailed Development Environment Setup](setup.md): If you are new to contributing
+     to Python packages, start here.
 -   [Create a Pull Request](pr.md)
--   Write and Run Tests - Coming Soon
--   Static Type Checks - Coming Soon
+-   [Write and Run Tests](tests.md)
 -   [Edit and Build Documentation](docs.md)
+-   Static Type Checks - Coming Soon
 -   Changelog Style - Coming Soon
 -   Linting and Formatting - Coming Soon
 

content/contributing/quick.md

@@ -1,8 +1,8 @@
 # Contributing Quick Reference
 
 This document assumes you have some familiarity with Git, GitHub, and Python
-virutalenvs. If you're not familiar with contributing to Python projects, you
-can refer to the [Detailed Development Environment Setup](setup.md) instead.
+virtual environments. If you're not familiar with contributing to Python projects, you
+can refer to [Development Environment Setup](setup.md) instead.
 
 These instructions will work with at least Bash and PowerShell, and should work
 on other shells. On Windows, use PowerShell, not CMD.
@@ -94,13 +94,19 @@ Any time you open a new terminal, you need to activate the virtualenv again. If
 you've pulled from upstream recently, you can re-run the `uv sync` command to
 get the current dev dependencies.
 
+Install the pre-commit hooks:
+
+```
+$ pre-commit install --install-hooks
+```
+
 ## Run Tests
 
 These are the essential test commands you can run while developing:
 
 -   `pytest` - Run the unit tests.
 -   `mypy` - Run the main type checker.
--   `tox run -e docs` - Build the documentation.
+-   `tox run -e docs,docs-auto` - Build the documentation in auto-reload mode. Navigate to `localhost:8000` to preview docs.
 
 These are some more specific commands if you need them:
 
@@ -113,11 +119,8 @@ These are some more specific commands if you need them:
     including unchanged and unstaged.
 -   `tox run -e py3.11` - Run unit tests with a specific Python version. The
     version must be installed. `-e pypy` will run against PyPy.
--   `pyright` - A second type checker.
 -   `tox run -e typing` - Run all typing checks. This includes `pyright` and its
     export check as well.
--   `python -m http.server -b 127.0.0.1 -d docs/_build/html` - Serve the
-    documentation.
 -   `tox run` and `tox parallel` can be shortened to `tox r` and `tox p`.
 
 ## Create a Pull Request

content/contributing/setup.md

@@ -1,8 +1,7 @@
 # Development Environment Setup
 
 This is a detailed guide on how to set up Python, Git, and a development
-environment for our projects. Each of our projects uses the same layout, making
-it easier to move between projects. Following these instructions will ensure
+environment for our projects. Following these instructions will ensure
 that every contributor has the same tools installed at the same versions in the
 same way, which makes it easier for everyone to help each other.
 
@@ -21,22 +20,44 @@ to the [Quick Reference](quick.md) instead.
     $ git config --global user.name 'your name'
     $ git config --global user.email 'your email'
     ```
-    -
 -   [Fork] the project to your GitHub account by clicking the "Fork" button.
+    Un-check the box that says "Copy the main branch only", as you will
+    also need the `stable` branch.
 -   Clone your fork locally, replacing `your-username` and `project` in the
     command below with your actual username and the actual project name. Change
     directory into the cloned project.
     ```
     $ git clone https://github.com/your-username/project
     $ cd project
     ```
--   Install the latest version of Python.
-    -   Linux: `python3` is likely already installed, otherwise use your
-        system's package manager to install it.
-    -   macOS/Windows: Download and run the appropriate installer from
-        https://python.org/downloads/. The yellow "Download" button near the top
-        left of the page will download the latest stable version.
--   Create and activate a virtualenv. Use the latest version of Python.
+
+[github]: https://github.com
+[git]: https://git-scm.com/downloads
+[name]: https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git
+[email]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address
+[Fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+
+## Install Python
+
+Install the latest version of Python.
+
+-   Linux: `python3` is likely already installed, otherwise use your
+    system's package manager to install it.
+-   macOS/Windows: Download and run the appropriate installer from
+    https://python.org/downloads/. The yellow "Download" button near the top
+    left of the page will download the latest stable version.
+
+
+## Install Python dependencies
+
+Pallets projects use two different ways of managing dependencies: `pip` and `uv`.
+Projects are being upgraded to use `uv`, but many projects still use `pip`.
+If the project has `requirements` folder, that means it is using the older `pip` flow.
+Check for that folder and follow the appropriate steps below.
+
+### Projects with a `requirements` directory
+
+-   Create and activate a virtualenv.
     -   Linux/macOS
         ```
         $ python3 -m venv .venv
@@ -52,22 +73,49 @@ to the [Quick Reference](quick.md) instead.
         > py -3 -m venv .venv
         > .venv\Scripts\activate
         ```
--   Install the development dependencies, then install Flask in editable mode.
+-   Install the development dependencies, then install the project in editable mode.
     In the future, you can run this again to update the dependencies.
     ```
     $ pip install -r requirements/dev.txt && pip install -e .
     ```
     -   On Windows CMD, `&&` doesn't work, so run the two commands separately.
--   Install the pre-commit hooks.
-    ```
-    $ pre-commit install --install-hooks
-    ```
 
-[github]: https://github.com
-[git]: https://git-scm.com/downloads
-[name]: https://docs.github.com/en/get-started/getting-started-with-git/setting-your-username-in-git
-[email]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address
-[Fork]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+### Projects without a `requirements` directory
+
+[Install `uv`.][uv]
+
+[uv]: https://docs.astral.sh/uv/getting-started/installation/
+
+Install dev dependencies:
+
+```
+$ uv sync
+```
+
+Activate the virtualenv (Mac and Linux):
+
+```
+$ . .venv/bin/activate
+```
+
+Activate the virtualenv (Windows):
+
+```
+> .\.venv\Scripts\activate
+```
+
+Any time you open a new terminal, you need to activate the virtualenv again. If
+you've pulled from upstream recently, you can re-run the `uv sync` command to
+get the current dev dependencies.
+
+## Install pre-commit hooks
+
+Pre-commit hooks automatically run linters and formatters before each git commit, catching style issues early so they don't appear as CI failures later.
+
+```
+$ pre-commit install --install-hooks
+```
+
 
 ## Debugger