From cfd2ba5495e4d8db138724b8c419a5e758be357b Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:08:43 +0000 Subject: [PATCH 1/6] docs: record the v2.15.0 release date and bump the install pins v2.15.0 is about to be published, so the site stops describing it as unreleased and the copy-pasteable snippets move to it. The changelog entry for v2.15.0 was written when the work merged and has carried "(unreleased)" since; it is now dated 2026-08-13. The five install pins outside the blog move from v2.14.0 to v2.15.0: configuration.md, example.md, index.md and both snippets in guides/integrations.md. Blog posts keep their pins, which record what was current when they were written. test_pinned_revisions_match_the_released_version fails for as long as PyPI does not have v2.15.0, since it compares every pin against the installed release. That is this change being ahead of the tag rather than wrong, and it goes green once the release is published. Nothing else in the suite is affected: 8 passed, 1 failed on that test alone. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/changelog.md | 2 +- docs/configuration.md | 2 +- docs/example.md | 2 +- docs/guides/integrations.md | 4 ++-- docs/index.md | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index c9fdcea..cad49ec 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -25,7 +25,7 @@ below and to the page that documents the feature properly. | [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Integrations](guides/integrations.md#across-an-organization) | | [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) | -## v2.15.0 (unreleased) { #v2150 } +## v2.15.0 (2026-08-13) { #v2150 } ### Added diff --git a/docs/configuration.md b/docs/configuration.md index 6b03041..ed1cf0c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -167,7 +167,7 @@ Used from a hook definition, with no config file anywhere in the repository: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.14.0 + rev: v2.15.0 hooks: - id: check-message args: diff --git a/docs/example.md b/docs/example.md index fc443cb..187339d 100644 --- a/docs/example.md +++ b/docs/example.md @@ -131,7 +131,7 @@ pushed: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.14.0 + rev: v2.15.0 hooks: - id: check-no-force-push stages: [pre-push] diff --git a/docs/guides/integrations.md b/docs/guides/integrations.md index e706f57..8a576bb 100644 --- a/docs/guides/integrations.md +++ b/docs/guides/integrations.md @@ -23,7 +23,7 @@ Add Commit Check to `.pre-commit-config.yaml`: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.14.0 + rev: v2.15.0 hooks: - id: check-message - id: check-branch @@ -70,7 +70,7 @@ Options can be passed as hook arguments, which keeps everything in one file: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.14.0 + rev: v2.15.0 hooks: - id: check-message args: diff --git a/docs/index.md b/docs/index.md index eb5e267..af331fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -36,7 +36,7 @@ whatever your AI agent is committing on your behalf. ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.14.0 + rev: v2.15.0 hooks: - id: check-message - id: check-branch From e990bac3a047592529e44f89a4404eb22737bea4 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:08:53 +0000 Subject: [PATCH 2/6] chore: add AGENTS.md so the site cannot quietly fall behind a release This repository documents behaviour that lives in another one, so its pages go stale without anything here changing: a release happens elsewhere, and the pins and the changelog keep describing the version before it. That has now happened twice -- v2.14.0 shipped on 12 August and the site still called it unreleased, with every pin naming v2.13.4. The guidelines make the check a standing rule rather than a release-time one: on every change, whatever the change is, look up the released version, compare it against the install pins and the changelog entry, and bring anything out of step into line in the same pull request. It also writes down the parts that are easy to get wrong: * A draft release is not released -- it has no tag and no package. * Blog pins are excluded on purpose; moving them would falsify a dated record. * tests/docs_sync_test.py needs the *released* package installed. A checkout of main reports 2.14.0.post1.dev6, which matches no pin. * Preparing a release ahead of its tag is the one case where the pin test may be red, and the response is to say so in the pull request, not to weaken the test. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3cc9a56 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,79 @@ +# AGENTS.md — AI Agent Guidelines + +This file provides working guidelines for AI coding agents (e.g., GitHub Copilot, Claude Code, Cursor, etc.) contributing to this repository. + +This repository is the documentation site for [commit-check](https://github.com/commit-check/commit-check). Everything here describes behaviour that lives in **another** repository, so the pages go stale on their own: a release happens elsewhere and nothing in this repository changes. The rules below exist to catch that. + +## Keep the site in step with the released version + +**Do this on every change, whatever you came here to do.** It is not a release-time task — the point is that no change leaves the site describing a version that no longer exists. + +1. **Find the latest released version.** + + ```console + $ curl -s https://pypi.org/pypi/commit-check/json | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])" + ``` + + The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question. A **draft** release is not released — it has no tag and no PyPI package, so it is not the answer here. + +2. **Check the install pins.** Every copy-pasteable snippet pins a revision, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. + + ```console + $ grep -rn "rev: v" docs | grep -v docs/blog + ``` + + Every one of those must name the released version. **Blog posts are excluded on purpose** — they are dated records of what was current when they were written, and moving their pins forward would falsify them. Never touch them. + +3. **Check the changelog.** `docs/changelog.md` must have an entry for the latest release, and that entry must carry its **release date**, not `(unreleased)`: + + ```markdown + ## v2.15.0 (2026-08-13) { #v2150 } + ``` + + The date is the release's own publication date, not today's. A release that is out but still marked `(unreleased)` here is the most common form of this drift. + + A notable release also needs a row in the **Highlights** table at the top, newest first, linking to its entry and to the page that documents the feature properly. A patch release that only fixes bugs does not need a row; a release that adds or changes user-visible behaviour does. + +4. **Anything out of step, fix it in the same change.** Do not open a follow-up issue and do not mention it in passing — bring it into step and say so in the pull request description. + +### Verify with the test suite + +The check above is automated, and the `docs-sync` job runs it on every pull request. Run it locally before you push: + +```console +$ python -m pip install pytest commit-check +$ pytest tests/ -q +``` + +`tests/docs_sync_test.py` reads the *installed* package and asserts the pins match it, along with every documented rule, option and default. Install the **released** package, not a checkout of `main` — a development version reports something like `2.14.0.post1.dev6`, which matches no pin and tells you nothing. + +### The one time pins may name an unreleased version + +When the site is being prepared for a release that has not been published yet, the pins and the changelog date are written **ahead** of the tag. `test_pinned_revisions_match_the_released_version` fails for as long as that is true, because PyPI does not have the version yet. That is expected, and it is the only acceptable reason for that test to be red: + +- Say so plainly in the pull request description. +- Do not weaken the test, and do not pin the `docs-sync` job to a version to make it pass. +- The pull request merges **after** the release is published, and CI is re-run to confirm it goes green. + +## Writing + +- The site documents what the tool **does**, in the version a reader can install today. If a page describes behaviour that only exists on `main`, it is wrong until that release ships. +- Pasted terminal output is a **transcript**: run the command and copy what it printed. Do not hand-write or adjust sample output — `tests/docs_sync_test.py` compares the rule names in those samples against the package and will catch an invented one. +- Prefer fixing a page over adding one. Every new page is another thing that can go stale. + +## Workflow + +- All changes must be submitted to the `main` branch **via a pull request**. Never push commits directly to `main`. +- Build the site before you push if you touched navigation, links or anything structural: `pipx run nox -s docs` (runs `mkdocs build --strict`, which fails on a broken internal link). + +## Git Rules + +- **Follow the Conventional Branch spec** for branch names: `/` with lowercase kebab-case descriptions. Allowed types: `feature/`, `bugfix/`, `hotfix/`, `release/`, `chore/`. Example: `chore/refresh-install-pins`. +- **Follow the Conventional Commits spec** for commit messages: `: ` (e.g., `feat: ...`, `fix: ...`, `chore: ...`, `docs: ...`). Most changes here are `docs:`. +- **No force push.** Never use `git push --force` or `git push --force-with-lease`. +- **Additive commits only.** When addressing review feedback, add new commits on top. Never rebase or squash history after the pull request is open. + +## Staging Files + +- Stage **only the files you changed**: `git add ...`. +- Never use `git add .` / `git add -A` / `git add --all`, and never stage unrelated or generated files. The built site lands in `site/` — it is never committed. From 48190029d20fa7c826d0a0f702d26e66a4cc1d58 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:15:27 +0000 Subject: [PATCH 3/6] docs: scope the pin rule to rev: snippets, and harden the verify commands Review found two ways the guidelines could send an agent to check the wrong thing. The pin rule claimed every copy-pasteable snippet carries a revision. Two do not: index.md references the action by its moving major tag (commit-check-action@v2) and runs the MCP server as an unversioned 'uvx commit-check-mcp'. Neither can go stale, and the grep beside the claim only ever matched 'rev:' anyway, so the text now says which snippets it means and why the other two are exempt. The verify commands could measure the wrong package. 'pip install commit-check' leaves an existing installation alone, so an agent that already had a release -- or the dev checkout this very section warns about -- would validate against that instead of the current one. And a bare 'pytest' can resolve to a different environment than the 'python' just installed into. Both are now '--upgrade' and 'python -m pytest', with a line each on why. Not changed: the '$ ' prompts, which markdownlint's MD014 objects to. This repository has no markdownlint configuration and does not lint markdown in CI; the prompt is the house style in 48 places across seven pages under docs/. Dropping it here would make this the only file that does it differently. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3cc9a56..f41b926 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ This repository is the documentation site for [commit-check](https://github.com/ The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question. A **draft** release is not released — it has no tag and no PyPI package, so it is not the answer here. -2. **Check the install pins.** Every copy-pasteable snippet pins a revision, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. +2. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. These are the only version-pinned snippets — the GitHub Action is referenced by its moving major tag (`commit-check-action@v2`) and `uvx commit-check-mcp` carries no version, so neither goes stale. ```console $ grep -rn "rev: v" docs | grep -v docs/blog @@ -41,11 +41,16 @@ This repository is the documentation site for [commit-check](https://github.com/ The check above is automated, and the `docs-sync` job runs it on every pull request. Run it locally before you push: ```console -$ python -m pip install pytest commit-check -$ pytest tests/ -q +$ python -m pip install --upgrade pytest commit-check +$ python -m pytest tests/ -q ``` -`tests/docs_sync_test.py` reads the *installed* package and asserts the pins match it, along with every documented rule, option and default. Install the **released** package, not a checkout of `main` — a development version reports something like `2.14.0.post1.dev6`, which matches no pin and tells you nothing. +`tests/docs_sync_test.py` reads the *installed* package and asserts the pins match it, along with every documented rule, option and default. Two details matter, and both are ways to check the wrong thing without noticing: + +- **`--upgrade` is not optional.** Without it, `pip` leaves an already-installed `commit-check` alone, so the run measures whatever was in the environment — quite possibly the release before the one you are checking against. +- **Run it as `python -m pytest`, not `pytest`.** A bare `pytest` can resolve to a different environment than the `python` you just installed into, and the version it then imports is not the one you think. + +Install the **released** package, not a checkout of `main` — a development version reports something like `2.14.0.post1.dev6`, which matches no pin and tells you nothing. ### The one time pins may name an unreleased version From 8d67111164ed9d23eb1a1d8bff496527ac0a0b95 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 05:17:53 +0000 Subject: [PATCH 4/6] docs: correct what a draft release proves The same overstatement review caught in commit-check#546. The note said a draft release "has no tag and no PyPI package"; neither half holds in general, since a draft can be saved against a tag that already exists and publishing to PyPI is a separate step from publishing the GitHub release. The advice was right and the reason was wrong, which is the worse half to get wrong in a rule an agent follows: it invites checking whether a tag exists and concluding from that alone that the version is out. The rule now turns on published versus draft, and points back at PyPI, which is what the pin check compares against. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index f41b926..4fbd395 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ This repository is the documentation site for [commit-check](https://github.com/ $ curl -s https://pypi.org/pypi/commit-check/json | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])" ``` - The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question. A **draft** release is not released — it has no tag and no PyPI package, so it is not the answer here. + The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question, provided you read only **published** releases. A draft is not one, and you cannot tell by looking for a tag: a draft can be saved against a tag that already exists, and publishing to PyPI is a separate step from publishing the GitHub release. Read the published release, or ask PyPI as above — PyPI is what the pin check compares against, since that is what a reader installs. 2. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. These are the only version-pinned snippets — the GitHub Action is referenced by its moving major tag (`commit-check-action@v2`) and `uvx commit-check-mcp` carries no version, so neither goes stale. From ff1aee66d197af23314a213765a205cb057ad183 Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Thu, 13 Aug 2026 09:37:12 +0300 Subject: [PATCH 5/6] Refine AGENTS.md for improved clarity Removed redundant phrases for clarity and consistency. --- AGENTS.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4fbd395..d9d8266 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,9 @@ # AGENTS.md — AI Agent Guidelines -This file provides working guidelines for AI coding agents (e.g., GitHub Copilot, Claude Code, Cursor, etc.) contributing to this repository. +This file provides working guidelines for AI coding agents contributing to this repository. -This repository is the documentation site for [commit-check](https://github.com/commit-check/commit-check). Everything here describes behaviour that lives in **another** repository, so the pages go stale on their own: a release happens elsewhere and nothing in this repository changes. The rules below exist to catch that. +This repository is the documentation site for [commit-check](https://github.com/commit-check/commit-check). Everything here describes behaviour that lives in **another** repository, +so the pages go stale on their own: a release happens elsewhere and nothing in this repository changes. The rules below exist to catch that. ## Keep the site in step with the released version @@ -14,9 +15,12 @@ This repository is the documentation site for [commit-check](https://github.com/ $ curl -s https://pypi.org/pypi/commit-check/json | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])" ``` - The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question, provided you read only **published** releases. A draft is not one, and you cannot tell by looking for a tag: a draft can be saved against a tag that already exists, and publishing to PyPI is a separate step from publishing the GitHub release. Read the published release, or ask PyPI as above — PyPI is what the pin check compares against, since that is what a reader installs. + The [releases page](https://github.com/commit-check/commit-check/releases) answers the same question, provided you read only **published** releases. + A draft is not one, and you cannot tell by looking for a tag: a draft can be saved against a tag that already exists, and publishing to PyPI is a + separate step from publishing the GitHub release. Read the published release, or ask PyPI as above — PyPI is what the pin check compares against, since that is what a reader installs. -2. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. These are the only version-pinned snippets — the GitHub Action is referenced by its moving major tag (`commit-check-action@v2`) and `uvx commit-check-mcp` carries no version, so neither goes stale. +3. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. + These are the only version-pinned snippets — the GitHub Action is referenced by its moving major tag (`commit-check-action@v2`) and `uvx commit-check-mcp` carries no version, so neither goes stale. ```console $ grep -rn "rev: v" docs | grep -v docs/blog @@ -24,7 +28,7 @@ This repository is the documentation site for [commit-check](https://github.com/ Every one of those must name the released version. **Blog posts are excluded on purpose** — they are dated records of what was current when they were written, and moving their pins forward would falsify them. Never touch them. -3. **Check the changelog.** `docs/changelog.md` must have an entry for the latest release, and that entry must carry its **release date**, not `(unreleased)`: +5. **Check the changelog.** `docs/changelog.md` must have an entry for the latest release, and that entry must carry its **release date**, not `(unreleased)`: ```markdown ## v2.15.0 (2026-08-13) { #v2150 } @@ -32,9 +36,10 @@ This repository is the documentation site for [commit-check](https://github.com/ The date is the release's own publication date, not today's. A release that is out but still marked `(unreleased)` here is the most common form of this drift. - A notable release also needs a row in the **Highlights** table at the top, newest first, linking to its entry and to the page that documents the feature properly. A patch release that only fixes bugs does not need a row; a release that adds or changes user-visible behaviour does. + A notable release also needs a row in the **Highlights** table at the top, newest first, linking to its entry and to the page that documents the feature properly. + A patch release that only fixes bugs does not need a row; a release that adds or changes user-visible behaviour does. -4. **Anything out of step, fix it in the same change.** Do not open a follow-up issue and do not mention it in passing — bring it into step and say so in the pull request description. +6. **Anything out of step, fix it in the same change.** Do not open a follow-up issue and do not mention it in passing — bring it into step and say so in the pull request description. ### Verify with the test suite @@ -52,7 +57,7 @@ $ python -m pytest tests/ -q Install the **released** package, not a checkout of `main` — a development version reports something like `2.14.0.post1.dev6`, which matches no pin and tells you nothing. -### The one time pins may name an unreleased version +### The one-time pins may name an unreleased version When the site is being prepared for a release that has not been published yet, the pins and the changelog date are written **ahead** of the tag. `test_pinned_revisions_match_the_released_version` fails for as long as that is true, because PyPI does not have the version yet. That is expected, and it is the only acceptable reason for that test to be red: From 22d22ac15491f5845ae00b5bae25b09cad9c7621 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 06:38:38 +0000 Subject: [PATCH 6/6] docs: repair the numbering and a hyphen the reflow changed Three mechanical slips from ff1aee6, which rewrapped the file. The rewrapping itself stands; only these are touched. The step list read 1, 3, 5, 6. CommonMark renumbers an ordered list from its first item, so the rendered page was never wrong -- but this file is read as source by the agents it instructs, and a list that skips numbers reads like steps are missing. The same slip happened in commit-check#546 and was corrected there. "The one time pins may name an unreleased version" became "The one-time pins may name an unreleased version", which changes what the heading says: the section is about the single occasion when a pin may run ahead of the tag, not about pins that are one-time. Rephrased to "The one case where pins may name an unreleased version", which carries the meaning without a hyphen that invites the same correction again. One line was also left with trailing whitespace. This repository has no pre-commit, so nothing would have removed it. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d9d8266..5332f57 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ This file provides working guidelines for AI coding agents contributing to this repository. -This repository is the documentation site for [commit-check](https://github.com/commit-check/commit-check). Everything here describes behaviour that lives in **another** repository, +This repository is the documentation site for [commit-check](https://github.com/commit-check/commit-check). Everything here describes behaviour that lives in **another** repository, so the pages go stale on their own: a release happens elsewhere and nothing in this repository changes. The rules below exist to catch that. ## Keep the site in step with the released version @@ -19,7 +19,7 @@ so the pages go stale on their own: a release happens elsewhere and nothing in t A draft is not one, and you cannot tell by looking for a tag: a draft can be saved against a tag that already exists, and publishing to PyPI is a separate step from publishing the GitHub release. Read the published release, or ask PyPI as above — PyPI is what the pin check compares against, since that is what a reader installs. -3. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. +2. **Check the install pins.** The pre-commit snippets pin a revision with `rev:`, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the page around it describes. These are the only version-pinned snippets — the GitHub Action is referenced by its moving major tag (`commit-check-action@v2`) and `uvx commit-check-mcp` carries no version, so neither goes stale. ```console @@ -28,7 +28,7 @@ so the pages go stale on their own: a release happens elsewhere and nothing in t Every one of those must name the released version. **Blog posts are excluded on purpose** — they are dated records of what was current when they were written, and moving their pins forward would falsify them. Never touch them. -5. **Check the changelog.** `docs/changelog.md` must have an entry for the latest release, and that entry must carry its **release date**, not `(unreleased)`: +3. **Check the changelog.** `docs/changelog.md` must have an entry for the latest release, and that entry must carry its **release date**, not `(unreleased)`: ```markdown ## v2.15.0 (2026-08-13) { #v2150 } @@ -39,7 +39,7 @@ so the pages go stale on their own: a release happens elsewhere and nothing in t A notable release also needs a row in the **Highlights** table at the top, newest first, linking to its entry and to the page that documents the feature properly. A patch release that only fixes bugs does not need a row; a release that adds or changes user-visible behaviour does. -6. **Anything out of step, fix it in the same change.** Do not open a follow-up issue and do not mention it in passing — bring it into step and say so in the pull request description. +4. **Anything out of step, fix it in the same change.** Do not open a follow-up issue and do not mention it in passing — bring it into step and say so in the pull request description. ### Verify with the test suite @@ -57,7 +57,7 @@ $ python -m pytest tests/ -q Install the **released** package, not a checkout of `main` — a development version reports something like `2.14.0.post1.dev6`, which matches no pin and tells you nothing. -### The one-time pins may name an unreleased version +### The one case where pins may name an unreleased version When the site is being prepared for a release that has not been published yet, the pins and the changelog date are written **ahead** of the tag. `test_pinned_revisions_match_the_released_version` fails for as long as that is true, because PyPI does not have the version yet. That is expected, and it is the only acceptable reason for that test to be red: