From c50feda0e34ee0e13fcfcaccafb756df78e3fbc5 Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 13 Aug 2026 05:11:06 +0000 Subject: [PATCH 1/5] docs: pin the README to v2.15.0, and make that a standing check The README's pre-commit snippets still named v2.12.2, three releases behind: 2.13.0, 2.13.4 and 2.14.0 had all shipped since. They are the first thing a new user copies, and the staleness is invisible -- the snippet keeps working, it just installs an older release than the page around it describes. Nothing in the test suite reads these pins, which is how they drifted that far. All three now name v2.15.0, the release being prepared. That is deliberately ahead of the tag: the release is published before this merges. AGENTS.md gains the check as a standing rule rather than a release-time one -- look up the released version, compare it against every pin in the README, and fix any that disagree in the same pull request. It also records two things that are easy to get wrong: a draft release is not released, and .pre-commit-config.yaml is deliberately excluded, because pre-commit resolves that pin against real tags at CI time, so pointing it at an unpublished version breaks the build. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 26 ++++++++++++++++++++++++++ README.md | 6 +++--- 2 files changed, 29 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 502ee494..7b40cf1f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,32 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot - All changes must be submitted to the `main` branch **via a pull request**. Never push commits directly to `main`. +## Keep the README pinned to the released version + +**Do this on every change, whatever you came here to do.** It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the README describes. Nothing in the test suite reads these pins, so only this check catches them. They had fallen three releases behind before anyone noticed. + +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 package, so it is not the answer here. + +2. **Check every pin in the README.** + + ```console + $ grep -n "rev: v" README.md + ``` + + Each one must name that version. Update any that do not, in the same pull request — do not open a follow-up issue for it. + +3. **Say so in the pull request description** when you moved them, so the bump is not a silent diff in an unrelated change. + +The one exception is a pull request that prepares an unpublished release: there the pins are written **ahead** of the tag, on purpose, and the release is published before the pull request merges. + +`.pre-commit-config.yaml` is a different case and is **not** covered by this rule. That pin is this repository running its own hooks, and pre-commit resolves it against real tags when CI runs — so pointing it at a version that is not published yet breaks the build. Bump it only after the release exists. + ## Git Rules - **Follow the Conventional Branch spec** for branch names: `/` with lowercase kebab-case descriptions. Allowed types: `feature/`, `bugfix/`, `hotfix/`, `release/`, `chore/`. Example: `chore/add-agent-guidelines`. diff --git a/README.md b/README.md index 0c37d438..e04f9e34 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ commit-check --message --branch ```yaml repos: - repo: https://github.com/commit-check/commit-check - rev: v2.12.2 + rev: v2.15.0 hooks: - id: check-message - id: check-branch @@ -196,7 +196,7 @@ commit-check --message # In pre-commit hooks (.pre-commit-config.yaml) repos: - repo: https://github.com/commit-check/commit-check - rev: v2.12.2 + rev: v2.15.0 hooks: - id: check-message args: @@ -226,7 +226,7 @@ commit-check --no-force-push # In pre-commit hooks (.pre-commit-config.yaml) repos: - repo: https://github.com/commit-check/commit-check - rev: v2.12.2 + rev: v2.15.0 hooks: - id: check-no-force-push stages: [pre-push] From f779adba79e70e97679b4d3f7430a4931b3971ab Mon Sep 17 00:00:00 2001 From: shenxianpeng Date: Thu, 13 Aug 2026 05:17:45 +0000 Subject: [PATCH 2/5] docs: correct what a draft release proves, and match the repo's code style Review found the draft-release note stating more than is true. It said a draft "has no tag and no package", and neither half holds in general: 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 in a rule an agent follows is the worse half to get wrong -- it invites checking for a tag and concluding the version is out. The rule now turns on published versus draft, and says what actually has to be true before a version can be pinned: the tag exists, because that is what pre-commit resolves rev: against, and PyPI has the version, because that is what installs. The command blocks also switch from ```console with '$ ' prompts to ```bash with bare commands, which is what README.md does in all five of its blocks. AGENTS.md had no code blocks before this branch, so the prompts were not this repository's style, they were mine. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- AGENTS.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7b40cf1f..42c5d339 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,16 +12,18 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot 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'])" + ```bash + 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 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. + + Both have to be true before a version can be pinned: the **tag** must exist, because that is what pre-commit resolves `rev:` against, and **PyPI** must have the version, because that is what installs. 2. **Check every pin in the README.** - ```console - $ grep -n "rev: v" README.md + ```bash + grep -n "rev: v" README.md ``` Each one must name that version. Update any that do not, in the same pull request — do not open a follow-up issue for it. From 9bf108557392837f2a5d014e3ace0f92f4edfc3e Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Thu, 13 Aug 2026 09:15:25 +0300 Subject: [PATCH 3/5] Update AGENTS.md --- AGENTS.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 42c5d339..81a3dadc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,8 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot ## Keep the README pinned to the released version -**Do this on every change, whatever you came here to do.** It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the README describes. Nothing in the test suite reads these pins, so only this check catches them. They had fallen three releases behind before anyone noticed. +**Do this on every change, whatever you came here to do.** It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, +and a stale pin is invisible: the snippet keeps working, it just installs an older release than the README describes. 1. **Find the latest released version.** @@ -16,11 +17,14 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot 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. + 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. - Both have to be true before a version can be pinned: the **tag** must exist, because that is what pre-commit resolves `rev:` against, and **PyPI** must have the version, because that is what installs. + Both have to be true before a version can be pinned: the **tag** must exist, because that is what pre-commit resolves `rev:` against, + and **PyPI** must have the version, because that is what installs. -2. **Check every pin in the README.** +3. **Check every pin in the README.** ```bash grep -n "rev: v" README.md @@ -28,11 +32,12 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot Each one must name that version. Update any that do not, in the same pull request — do not open a follow-up issue for it. -3. **Say so in the pull request description** when you moved them, so the bump is not a silent diff in an unrelated change. +4. **Say so in the pull request description** when you moved them, so the bump is not a silent diff in an unrelated change. The one exception is a pull request that prepares an unpublished release: there the pins are written **ahead** of the tag, on purpose, and the release is published before the pull request merges. -`.pre-commit-config.yaml` is a different case and is **not** covered by this rule. That pin is this repository running its own hooks, and pre-commit resolves it against real tags when CI runs — so pointing it at a version that is not published yet breaks the build. Bump it only after the release exists. +`.pre-commit-config.yaml` is a different case and is **not** covered by this rule. That pin is this repository running its own hooks, +and pre-commit resolves it against real tags when CI runs — so pointing it at a version that is not published yet breaks the build. Bump it only after the release exists. ## Git Rules From b8638dc72ff290773572694bc300516ded390302 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 06:15:37 +0000 Subject: [PATCH 4/5] ci: auto fixes from pre-commit.com hooks --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 81a3dadc..877667f6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,7 @@ This file provides working guidelines for AI coding agents (e.g., GitHub Copilot ## Keep the README pinned to the released version -**Do this on every change, whatever you came here to do.** It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, +**Do this on every change, whatever you came here to do.** It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the README describes. 1. **Find the latest released version.** @@ -36,7 +36,7 @@ and a stale pin is invisible: the snippet keeps working, it just installs an old The one exception is a pull request that prepares an unpublished release: there the pins are written **ahead** of the tag, on purpose, and the release is published before the pull request merges. -`.pre-commit-config.yaml` is a different case and is **not** covered by this rule. That pin is this repository running its own hooks, +`.pre-commit-config.yaml` is a different case and is **not** covered by this rule. That pin is this repository running its own hooks, and pre-commit resolves it against real tags when CI runs — so pointing it at a version that is not published yet breaks the build. Bump it only after the release exists. ## Git Rules From e97b85e26b121c9aef8c6c422f8b560a181bb6fe Mon Sep 17 00:00:00 2001 From: Xianpeng Shen Date: Thu, 13 Aug 2026 09:16:08 +0300 Subject: [PATCH 5/5] Fix numbering in AGENTS.md for clarity --- AGENTS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 877667f6..d0698b4a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ and a stale pin is invisible: the snippet keeps working, it just installs an old Both have to be true before a version can be pinned: the **tag** must exist, because that is what pre-commit resolves `rev:` against, and **PyPI** must have the version, because that is what installs. -3. **Check every pin in the README.** +2. **Check every pin in the README.** ```bash grep -n "rev: v" README.md @@ -32,7 +32,7 @@ and a stale pin is invisible: the snippet keeps working, it just installs an old Each one must name that version. Update any that do not, in the same pull request — do not open a follow-up issue for it. -4. **Say so in the pull request description** when you moved them, so the bump is not a silent diff in an unrelated change. +3. **Say so in the pull request description** when you moved them, so the bump is not a silent diff in an unrelated change. The one exception is a pull request that prepares an unpublished release: there the pins are written **ahead** of the tag, on purpose, and the release is published before the pull request merges.