breaking change: how a release is cut, agnostic and Python - #6
Merged
Merged
Conversation
The version scheme was standardised; the act of releasing was not. §5 said what a number means and LIBRARY.md said what artifacts a release produces, but nothing said how one gets out — the order, what cannot be undone, and what to check afterwards. Every trap in the new §5.1 fired on a Codechu release this month: a bump that moved one version record of four; a job that published to the index and then failed for want of a write permission, leaving a state no re-run could repair; and a release guide still instructing a step the pipeline had stopped performing. The Python half — where the version hides, generating the long description rather than maintaining it, trusted publishing, and pipx before pip for tools — is in lang/python/RELEASING.md, linked from the layer index. That index also carried a dead anchor into STANDARDS §13 "Active repositories", which has been §14 for some time.
There was a problem hiding this comment.
Pull request overview
This PR strengthens the organization’s documentation around how releases are cut, adding a language-agnostic procedure to STANDARDS.md and a Python-specific releasing guide that maps those rules onto PyPI workflows. It also updates the Python layer index to include the new guide and fixes a previously dead anchor reference.
Changes:
- Added
STANDARDS.md§5.1 documenting an ordered, tag-triggered release procedure with verification and permissions guidance. - Added
lang/python/RELEASING.mddescribing Python-specific release concerns (version locations, long description generation, trusted publishing, and ordering). - Updated
lang/python/README.mdto link the new releasing guide and fix the “Active repositories” anchor to §14.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| STANDARDS.md | Adds an org-wide “Cutting a release” section under versioning/commits. |
| lang/python/RELEASING.md | New Python-specific release playbook extending the org-wide release procedure. |
| lang/python/README.md | Indexes the new Python releasing doc and fixes the active-repos anchor link. |
Suppressed comments (3)
STANDARDS.md:166
- Spelling consistency: “artefacts/colour” use British spelling, but STANDARDS.md already uses American spelling (e.g., “Color palette”). Consider standardizing here to match the rest of the doc.
5. **Verify the artefacts, not the colour of the run** — in **both**
lang/python/RELEASING.md:16
- Spelling consistency: this table row uses “artefact”, but other Python docs use “artifact”.
| `<package>/__init__.py` | what the running tool reports, and what any artefact it produces is stamped with |
lang/python/RELEASING.md:25
- Spelling consistency: “artefact” is used twice in this paragraph, but other docs use “artifact”.
shipping. `__init__.py` is the quiet one: it is what a produced artefact
records, and an artefact stamped with a version that did not produce it
cannot be reproduced.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+147
to
+148
| The version scheme above says what a number means. This says how one gets | ||
| out, and every line of it was paid for. |
Comment on lines
+152
to
+154
| hand moves some of them. *Incident: a release bumped the packaging | ||
| metadata and left three other records behind, so every artefact that | ||
| release produced was stamped with a version that did not produce it.* |
| irreversible step**, and grant the job the permissions its *last* step | ||
| needs — not its first. Publication to a package index cannot be undone | ||
| or repeated. *Incident: a release job published to the index and then | ||
| failed creating the source-forge release for want of a write |
|
|
||
| Extends [`STANDARDS.md` §5.1](../../STANDARDS.md#51-cutting-a-release), | ||
| which carries the language-agnostic rules. This is what §5.1 means when | ||
| the artefact is a wheel on PyPI. |
Comment on lines
+31
to
+32
| **generate it** and check it in CI — a copy maintained by remembering to | ||
| is a copy that ships one revision behind, and only a reader notices. |
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
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.
STANDARDS.mdgave the version scheme andLIBRARY.mdthe release artifacts, but nothing said how a release is cut. Three traps fired on Codechu releases this month, all in that gap.§5.1 (language-agnostic) — one command moves every version record and a test asserts they agree; the changelog entry precedes the tag; the tag is the only trigger and pushing it is the human signature; the pipeline is ordered so everything that can fail runs before the irreversible step, and the job gets the permissions its last step needs; verify the artefacts rather than the colour of the run, in both directions (a green run can leave a half-finished release, a red run can sit above a good one); and the procedure names its tooling and is re-read when the tooling changes.
lang/python/RELEASING.md— the four places a Python version hides, generating the PyPI long description instead of maintaining it, trusted publishing withcontents: writefor anything after the upload, the order that survives, and pipx-before-pip for tools.Also fixes a dead anchor in the Python layer index (
STANDARDS.md#13-active-repositories; that section has been §14 for some time) — found by walking every in-repo anchor, which now reports clean.