From 61fa2fe19c25203112ed9f75f19594c65243fd28 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 18 May 2026 09:35:06 -0700 Subject: [PATCH 1/4] Add pre-commit hooks installation instructions to uv section Added instructions for installing pre-commit hooks. --- content/contributing/quick.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/contributing/quick.md b/content/contributing/quick.md index ca88eff..55c54ca 100644 --- a/content/contributing/quick.md +++ b/content/contributing/quick.md @@ -94,6 +94,12 @@ 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: From ca583ff18247482b064bbaa208d702b6fd7bf736 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 18 May 2026 09:53:57 -0700 Subject: [PATCH 2/4] Remove redundant reference info, update references to it --- content/contributing/layout.md | 2 +- content/contributing/pr.md | 2 +- content/contributing/quick.md | 4 ++-- content/contributing/setup.md | 32 +------------------------------- 4 files changed, 5 insertions(+), 35 deletions(-) diff --git a/content/contributing/layout.md b/content/contributing/layout.md index e626d1b..14d4c3f 100644 --- a/content/contributing/layout.md +++ b/content/contributing/layout.md @@ -68,7 +68,7 @@ The `.pre-commit-config.yaml` file pins the versions of each tool. [pre-commit.ci] runs these checks and commits fixes automatically on pull requests. It will also make PRs to update the pinned versions each month. -See [setup](setup.md) for how to enable pre-commit. +See [contributing reference](quick.md) for how to enable pre-commit. [black] enforces code formatting. diff --git a/content/contributing/pr.md b/content/contributing/pr.md index 596705f..9e00ab5 100644 --- a/content/contributing/pr.md +++ b/content/contributing/pr.md @@ -9,7 +9,7 @@ issue is not marked as assigned (in the sidebar) and is not already linked to an open PR. Do not ask to be assigned to an issue. Maintainers only use assignment for themselves or during live sprints to avoid conflicting work. -Check [Environment Setup](setup.md) or [Quick Reference](quick.md) for how to +Check [Contributing Reference](quick.md) for how to set up your development environment and run tests. This guide assumes you've done that and used the GitHub CLI to fork and clone the repository and add the upstream remote. diff --git a/content/contributing/quick.md b/content/contributing/quick.md index 55c54ca..a9e4811 100644 --- a/content/contributing/quick.md +++ b/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 Git/GitHub, 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. diff --git a/content/contributing/setup.md b/content/contributing/setup.md index 12477e7..123163f 100644 --- a/content/contributing/setup.md +++ b/content/contributing/setup.md @@ -1,10 +1,6 @@ # 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 -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. +This is a detailed guide on how to set up Python and Git. If you're already familiar with contributing to Python projects, you can refer to the [Quick Reference](quick.md) instead. @@ -36,32 +32,6 @@ to the [Quick Reference](quick.md) instead. - 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. - - Linux/macOS - ``` - $ python3 -m venv .venv - $ . .venv/bin/activate - ``` - - On Ubuntu or Debian, you'll need to install `venv` first, otherwise - the above command will fail. - ``` - $ sudo apt install python3-venv - ``` - - Windows - ``` - > py -3 -m venv .venv - > .venv\Scripts\activate - ``` -- Install the development dependencies, then install Flask 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 From 629347179d8ddbea6b594502301db32807590e8c Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 18 May 2026 11:48:34 -0700 Subject: [PATCH 3/4] Update the detailed setup guide --- content/contributing/index.md | 9 ++-- content/contributing/layout.md | 2 +- content/contributing/pr.md | 2 +- content/contributing/quick.md | 7 +-- content/contributing/setup.md | 94 +++++++++++++++++++++++++++++++--- 5 files changed, 95 insertions(+), 19 deletions(-) diff --git a/content/contributing/index.md b/content/contributing/index.md index 33c1a38..f9d80af 100644 --- a/content/contributing/index.md +++ b/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 diff --git a/content/contributing/layout.md b/content/contributing/layout.md index 14d4c3f..c5702f6 100644 --- a/content/contributing/layout.md +++ b/content/contributing/layout.md @@ -68,7 +68,7 @@ The `.pre-commit-config.yaml` file pins the versions of each tool. [pre-commit.ci] runs these checks and commits fixes automatically on pull requests. It will also make PRs to update the pinned versions each month. -See [contributing reference](quick.md) for how to enable pre-commit. +See [setup](setup.md#install-pre-commit-hooks) for how to enable pre-commit. [black] enforces code formatting. diff --git a/content/contributing/pr.md b/content/contributing/pr.md index 9e00ab5..596705f 100644 --- a/content/contributing/pr.md +++ b/content/contributing/pr.md @@ -9,7 +9,7 @@ issue is not marked as assigned (in the sidebar) and is not already linked to an open PR. Do not ask to be assigned to an issue. Maintainers only use assignment for themselves or during live sprints to avoid conflicting work. -Check [Contributing Reference](quick.md) for how to +Check [Environment Setup](setup.md) or [Quick Reference](quick.md) for how to set up your development environment and run tests. This guide assumes you've done that and used the GitHub CLI to fork and clone the repository and add the upstream remote. diff --git a/content/contributing/quick.md b/content/contributing/quick.md index a9e4811..69c5fbd 100644 --- a/content/contributing/quick.md +++ b/content/contributing/quick.md @@ -1,7 +1,7 @@ # Contributing Quick Reference This document assumes you have some familiarity with Git, GitHub, and Python -virtual environments. If you're not familiar with Git/GitHub, you +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 @@ -106,7 +106,7 @@ 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: @@ -119,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 diff --git a/content/contributing/setup.md b/content/contributing/setup.md index 123163f..55a359e 100644 --- a/content/contributing/setup.md +++ b/content/contributing/setup.md @@ -1,6 +1,9 @@ # Development Environment Setup -This is a detailed guide on how to set up Python and Git. +This is a detailed guide on how to set up Python, Git, and a development +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. If you're already familiar with contributing to Python projects, you can refer to the [Quick Reference](quick.md) instead. @@ -17,8 +20,9 @@ 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. @@ -26,12 +30,6 @@ to the [Quick Reference](quick.md) instead. $ 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. [github]: https://github.com [git]: https://git-scm.com/downloads @@ -39,6 +37,86 @@ to the [Quick Reference](quick.md) instead. [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 + $ . .venv/bin/activate + ``` + - On Ubuntu or Debian, you'll need to install `venv` first, otherwise + the above command will fail. + ``` + $ sudo apt install python3-venv + ``` + - Windows + ``` + > py -3 -m venv .venv + > .venv\Scripts\activate + ``` +- 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. + +### 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 Many IDEs, including [PyCharm] and [VS Code], include a debugger UI. There are also From 0ee8d4a8a42ba81792a5165088b64465e2c906d3 Mon Sep 17 00:00:00 2001 From: Pamela Fox Date: Mon, 18 May 2026 11:52:54 -0700 Subject: [PATCH 4/4] Revert anchor change, didnt work --- content/contributing/layout.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/contributing/layout.md b/content/contributing/layout.md index c5702f6..e626d1b 100644 --- a/content/contributing/layout.md +++ b/content/contributing/layout.md @@ -68,7 +68,7 @@ The `.pre-commit-config.yaml` file pins the versions of each tool. [pre-commit.ci] runs these checks and commits fixes automatically on pull requests. It will also make PRs to update the pinned versions each month. -See [setup](setup.md#install-pre-commit-hooks) for how to enable pre-commit. +See [setup](setup.md) for how to enable pre-commit. [black] enforces code formatting.