neuwirth
/
pmacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(release): a tag before the merge does nothing, silently 

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) <noreply@anthropic.com>
This commit is contained in:
Levi Neuwirth 2026-08-01 14:46:27 -04:00
parent 84b1620e7e
commit d0570cdf72
No known key found for this signature in database
1 changed files with 11 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/distribution-stage1-framing.md
View File

@ -417,6 +417,17 @@ One branch, `distribution-stage1`:
acceptance 2–8 against the published artifacts. acceptance 2–8 against the published artifacts.
6. **Tag `v1.1.0` from that same verified SHA.** 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 **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 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 merge — and it is cut *from the merge SHA*, so the final tag can reuse