From 08678a52767ba994ecc553d95fa70d545ac7bdf9 Mon Sep 17 00:00:00 2001 From: "Daniel Plohmann (bismuth)" Date: Fri, 11 Sep 2026 17:14:46 +0200 Subject: [PATCH] docs(docs): track release scope in a milestone named for the tag Four times today the question 'what is left before v4.7.0' was answered by re-reading the issue list and the PR list and working out which of them mattered. The scope was spread across an issue acting as an ad-hoc tracker (#322), the handover sections of out-of-repo session notes, and PR bodies. None of those is queryable and the first two are maintained by hand. The Unreleased section #337 introduced covers the other half well -- it is the record of what landed and what it cost -- but it is silent on what has not landed, which is the half the question is actually about. A milestone per release is the thin version of the missing piece: one bucket holding issues and PRs, a closed/total count, and a filter. It does not order work and nothing assigns it automatically, so a PR joins when it is accepted for the release rather than when it is opened -- otherwise it accumulates into a wishlist and the count stops meaning anything. v4.7.0 exists and carries #328 and #329. No CHANGELOG entry: this changes how the repository is organised and nothing a consumer of the package can observe. Raised in the PR, since it is the second change today where 'every PR writes a bullet' meets a PR with nothing user-facing to say. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 286613f4..4f5b8265 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,6 +119,13 @@ When a change warrants a version bump, update **all three** in one commit: Keep the two version strings in sync. Do not bump versions unless the change is a release-worthy change (and see Git Workflow re: explicit ask). +**Scope lives in a milestone named for the tag.** A PR joins `vX.Y.Z` when it is accepted for that +release rather than when it is opened, so the milestone stays a list of what is left rather than a +wishlist; issues that have to close for the release join it too. Cut when it reads 100% and `master` +is green, and close it when the tag is pushed. It answers "what is left before the release" as a +query instead of a re-read of the issue and PR lists, which is the half `CHANGELOG.md` cannot cover: +the changelog records what landed and what it cost, the milestone what has not landed yet. + **Tag after `master` is green, not at merge.** A tag created on the merge commit before CI has confirmed the merged tree can need moving, and moving one a PyPI publish has already consumed is a different problem from moving one nobody has fetched. Every other PR writes its own bullet under `## [Unreleased]` as it merges, rather than the release being reconstructed from merge commits afterwards — see *How an entry is written* in `CHANGELOG.md` for the subsections, the scope prefix and the four content rules. `.github/workflows/changelog.yml` requires a PR touching `src/smda/` to touch `CHANGELOG.md` or carry the `no-changelog` label.