S3 — Give the publishing runbook a pre-tag checklist - #277
Merged
Merged
Conversation
S3 of epic #267. Closes #270. The runbook had none. Its §TL;DR and §C are numbered process narratives — bump, rehearse, `gh release create`, confirm — with no step verifying the preconditions a MAJOR carries. So register C-13's requirement ("before tagging: confirm every consumer repo has an adoption issue filed") lived only in the risk register, which is not the document anyone stands in front of at release time. That is exactly how 2.0.0 reached "ready to tag" with zero adoption issues filed: the rule existed and was invisible at the moment it applied. The checklist sits immediately before `gh release create` — the point of no return, since a PyPI version can never be reused — and §C now points at it. Six items for every release, three for MAJORs only. Short enough to actually run. Two choices worth recording. The consumer-discovery step tells you to find the pinned repos **by their pins**, with the command, rather than from memory; a remembered list is how a fourth consumer gets missed. And it stays prose rather than a script: the adoption-issue condition needs network and cross-repo credentials, which the `docs` CI job deliberately does not have. The static half of this problem is check 10; this is the half a human has to read. Walked against the current state rather than asserted to work: CI green on the exact commit PASS (11/11) validate_docs.sh PASS check_arch_tree.py PASS twine check PASS wheel carries 3 packages + py.typed PASS CHANGELOG entry, no [Unreleased] PASS adoption issue per pinned consumer *** FAIL — 0 of 3 *** conformance floor decided PASS ADR records decision + migration PASS The one failure is the omission this release actually has. The checklist would have caught it before the tag, which is the only claim being made for it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
S3 of epic #267. Closes #270.
The problem
The runbook had no checklist. §TL;DR and §C are numbered process narratives with no step verifying what a MAJOR carries.
So register C-13's requirement — "before tagging: confirm every consumer repo has an adoption issue filed" — lived only in the risk register, which is not the document anyone stands in front of at release time. That is exactly how 2.0.0 reached "ready to tag" with zero adoption issues filed: the rule existed and was invisible at the moment it applied.
What was added
A checklist immediately before
gh release create— the point of no return, since a PyPI version can never be reused — with §C pointing at it. Six items every release, three for MAJORs only.Two choices worth recording:
docsCI job deliberately does not have. The static half of this problem is check 10 (S1 — Kill the two-package claim as a class, and add validate_docs check 10 (Epic #267) #268); this is the half a human has to read.Walked against the current state, not asserted
The single failure is the omission this release actually has — S4 (#271), the maintainer's story. Catching that before the tag is the only claim being made for this checklist.
Verification
🤖 Generated with Claude Code