From d0570cdf726f687c23925f4b0ee3bfd3f1148fcd Mon Sep 17 00:00:00 2001 From: Levi Neuwirth Date: Sat, 1 Aug 2026 14:46:27 -0400 Subject: [PATCH] docs(release): a tag before the merge does nothing, silently MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Operational note for ยง7's step 5, recorded before it can bite rather than after. For `on: push: tags`, GitHub resolves the workflow file AS IT EXISTS AT THE TAGGED COMMIT, and it registers a repository's workflows from the DEFAULT BRANCH. Verified while #211 was in review: `gh workflow list` reports only CI, because release.yml lives on the branch and not yet on main. So tagging any commit that predates the merge produces no run, no error, and no release. That failure mode is worse than a red one: a silent no-op is indistinguishable from "the run has not started yet", which is exactly what someone watching for an RC would assume. Cut the RC from the merge SHA and confirm a run actually appeared before drawing any conclusion from its absence. Co-Authored-By: Claude Opus 5 (1M context) --- docs/distribution-stage1-framing.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/distribution-stage1-framing.md b/docs/distribution-stage1-framing.md index 833b43c..9600e56 100644 --- a/docs/distribution-stage1-framing.md +++ b/docs/distribution-stage1-framing.md @@ -417,6 +417,17 @@ One branch, `distribution-stage1`: acceptance 2โ€“8 against the published artifacts. 6. **Tag `v1.1.0` from that same verified SHA.** +**A tag before the merge does nothing, silently.** For `on: push: +tags`, GitHub resolves the workflow file **as it exists at the tagged +commit** โ€” and it lists a repository's workflows from the *default +branch*, so `release.yml` is not even registered until this PR merges +(verified: `gh workflow list` shows only CI while the file lives on the +branch). Tagging any commit that predates the merge therefore produces +no run, no error, and no release. **A silent no-op is the worst possible +outcome for a release step, because it is indistinguishable from "not +started yet."** Cut the RC from the merge SHA and confirm a run actually +appeared before concluding anything about it. + **Steps 5 and 6 are the point of the ordering.** A tag on a branch would publish a release from unmerged code, so the RC necessarily follows the merge โ€” and it is cut *from the merge SHA*, so the final tag can reuse