docs: repair release workflow anchors after preflight shift
All checks were successful
CI / release-exercise (pull_request) Successful in 15s
CI / self-guards (pull_request) Successful in 16s
CI / action-exercise (pull_request) Successful in 12s
CI / docs-sync-exercise (pull_request) Successful in 12s
labels / labels (pull_request) Successful in 16s
CI / test (pull_request) Successful in 5m17s
Refs guard / refs-not-closing (pull_request) Successful in 7s

This commit is contained in:
codex-bot-andresmgsl 2026-08-31 15:55:21 +00:00
parent 715663cf53
commit d944bddecc

View file

@ -108,7 +108,7 @@ workflow that carries it.
consumer's release, when it is stale.)
**The merge is the ship decision; the tag is transcription.** After the
merge, [release.yml](.github/workflows/release.yml#L136-L301) asserts its
merge, [release.yml](.github/workflows/release.yml#L136-L310) asserts its
way to certainty, tags the merge commit, publishes the forge release with
the version's own changelog section as the body — the curated prose, never
the generated PR list ([lib/changelog.sh](lib/changelog.sh) is the one
@ -142,20 +142,20 @@ this file that leaves a real release behind.
`release`-labeled PR whose version transitioned to bare is the ceremony,
everything legitimate that isn't one is a green no-op, and every
half-ceremony dies loudly
([release.yml](.github/workflows/release.yml#L136-L301)). Use it for every
([release.yml](.github/workflows/release.yml#L136-L310)). Use it for every
normal release.
- **The tag door — the fallback and the backfill.** A bare `X.Y.Z` tag push
**no `v` prefix**, box's 0.6.0 set the scheme
([release.yml](.github/workflows/release.yml#L316-L401)) — publishes the
([release.yml](.github/workflows/release.yml#L325-L410)) — publishes the
same way. The tag is the operator's explicit act, so there is no decide
and no label check — what is left is three asserts: **the tag names the
tree's own version**
([L341L352](.github/workflows/release.yml#L341-L352)), **the tagged
([L350L361](.github/workflows/release.yml#L350-L361)), **the tagged
tree carries a publishable `## X.Y.Z` section**
([L353L365](.github/workflows/release.yml#L353-L365)), and **no published
([L362L374](.github/workflows/release.yml#L362-L374)), and **no published
release already exists for the tag**
([L366L381](.github/workflows/release.yml#L366-L381)); any failure
([L375L390](.github/workflows/release.yml#L375-L390)); any failure
refuses, creating nothing. No `-dev` bump either
— the fallback does not rewrite main (cast's precedent). Use it when the
merge path is red, for backfills, and for the
@ -473,7 +473,7 @@ so this line can only appear when some *other* caller invokes `version_read`
directly with a backend that is neither `file` nor `package-json`. Fix that
caller.
### The merge door refused ([release.yml](.github/workflows/release.yml#L136-L301))
### The merge door refused ([release.yml](.github/workflows/release.yml#L136-L310))
> CHANGELOG.md has no '## $VER' section at the merge commit — the ceremony PR must stamp it; refusing to publish an empty release
@ -497,7 +497,7 @@ and re-push the tag from the fixed tree, or run `forge_release_create` by hand.
> direct push refused (branch protection?) — opening the bump PR instead
[L293L301](.github/workflows/release.yml#L293-L301) — loud, but not a
[L302L310](.github/workflows/release.yml#L302-L310) — loud, but not a
refusal: the post-release `-dev` bump could not push directly, so the run
opened a `release`-labeled bump PR itself. Your move: merge it promptly —
until it lands, main is sitting bare, where a dev install impersonates the
@ -505,35 +505,35 @@ release and the
[armed guard's window](#changelog-armed--main-never-sits-disarmed) stays
open.
### The tag door refused ([release.yml](.github/workflows/release.yml#L316-L401))
### The tag door refused ([release.yml](.github/workflows/release.yml#L325-L410))
> tag '$GITHUB_REF_NAME' does not match the tree's version '$ver' — creating nothing.
> A release is a PR, then a tag: the release PR bumps the version and stamps the changelog; the tag goes on its MERGE commit. Delete this tag and re-tag the right commit.
[L347L350](.github/workflows/release.yml#L347-L350). The message is the
[L356L359](.github/workflows/release.yml#L356-L359). The message is the
remedy.
> CHANGELOG.md has no '## $VER' section — run changelog-assemble in the release PR before tagging; refusing to publish an empty release
[L359L365](.github/workflows/release.yml#L359-L365). The tagged tree was
[L368L374](.github/workflows/release.yml#L368-L374). The tagged tree was
never stamped. Assemble the section
([docs/CONSUMERS.md](docs/CONSUMERS.md#assembling-a-release-section)), then
delete and re-push the tag.
> release '$VER' already exists — refusing to re-release, creating nothing.
[L366L381](.github/workflows/release.yml#L366-L381). A published release is
[L375L390](.github/workflows/release.yml#L375-L390). A published release is
never replaced by the fallback. If it is correct, there is nothing to do; if
it is wrong, correct that published artifact deliberately before retrying.
### The re-arm refused ([release.yml](.github/workflows/release.yml#L267-L301))
### The re-arm refused ([release.yml](.github/workflows/release.yml#L276-L310))
The bump belongs to the merge door alone — the tag door deliberately does not
rewrite main ([L316L320](.github/workflows/release.yml#L316-L320)) — and it
rewrite main ([L325L329](.github/workflows/release.yml#L325-L329)) — and it
runs *after* the tag, the notes and the publish. So a refusal here leaves a
real release standing behind a main that never re-armed — the release exists,
and main is left *armed to impersonate* it, still reading the version it just
shipped ([L266](.github/workflows/release.yml#L266)). That is the one failure
shipped ([L275](.github/workflows/release.yml#L275)). That is the one failure
in this catalog whose remedy is a manual bump, not a re-run.
> version_next_dev: refusing '$ver' — expected bare X.Y.Z
@ -581,7 +581,7 @@ In every case the remedy has the same shape — bump `VERSION` (or the
shipped version was bare, and where it was an rc, whatever you have decided
comes next. Note that a *push* refusal is not one of these — branch
protection is expected, and the step opens the bump PR itself rather than
failing ([L293L301](.github/workflows/release.yml#L293-L301)).
failing ([L302L310](.github/workflows/release.yml#L302-L310)).
### Red main that is not the release workflow