From 873d5c8b450eadce917bd8e75d366f273d30a31f Mon Sep 17 00:00:00 2001 From: "Daniel Plohmann (bismuth)" Date: Tue, 15 Sep 2026 08:47:00 +0200 Subject: [PATCH] say which tags can be rehearsed, and which cannot "Choosing a tag as the ref" is true only of a tag cut after the workflow existed. A manual run resolves the workflow file, and checks out the guard script it calls, from the ref it is given, so v0.5.0 and earlier carry neither and fail in a way that does not name the cause. Verified against this repository: `git ls-tree v0.5.0 .github/workflows/` lists the old release.yml and no publish-release.yml, and no scripts/ at all. The same property is worth stating as the reassurance it also is: those three tags cannot trigger a publish if one is ever re-pushed. Also records how to rehearse a version before it ships, which the required reviewer on the `pypi` environment is what makes possible: the tag push parks the real run at the publish job, the rehearsal runs from the same tag while it waits, and the decision to approve or reject comes after. Co-Authored-By: Claude Opus 5 (1M context) --- RELEASING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 9025a3a..4414e33 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -108,6 +108,16 @@ through the same gates and build, publishes to [TestPyPI](https://test.pypi.org/ PyPI (an already-present version is skipped rather than failed), and stops before creating the GitHub release. Rehearse the first release after any change to the workflow. +The tag has to be one cut after this workflow was added. A manual run reads the workflow, and +checks out the guard script, from the ref it is given, so a tag from before neither carries them: +`v0.5.0` and earlier cannot be rehearsed, and the failure does not say why. The same property is +what makes those tags inert — re-pushing one triggers nothing. + +A rehearsal and the real release can both be in flight on one tag, which is how to rehearse a +version before it goes out. Pushing the tag starts the real run, and a required reviewer on the +`pypi` environment holds it at the publish job; rehearse from the same tag while it waits, then +approve it, or reject it and leave the version number unused. + ## When a release fails - **A gate failed before anything was published** (tag/version mismatch, missing changelog section,