heavy-duty/ceremony
7
0
Fork 2
Code Issues 1 Pull requests Projects Releases 8 Packages Wiki Activity Actions

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

Browse source
This commit is contained in:
codex-bot-andresmgsl 2026-08-31 15:55:21 +00:00
parent 715663cf53
commit d944bddecc
1 changed files with 16 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
README.md
View file

@ -108,7 +108,7 @@ workflow that carries it.
consumer's release, when it is stale.) consumer's release, when it is stale.)
**The merge is the ship decision; the tag is transcription.** After the **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 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 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 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, `release`-labeled PR whose version transitioned to bare is the ceremony,
everything legitimate that isn't one is a green no-op, and every everything legitimate that isn't one is a green no-op, and every
half-ceremony dies loudly 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. normal release.
- **The tag door — the fallback and the backfill.** A bare `X.Y.Z` tag push - **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 — **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 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 and no label check — what is left is three asserts: **the tag names the
tree's own version** tree's own version**
([L341–L352](.github/workflows/release.yml#L341-L352)), **the tagged ([L350–L361](.github/workflows/release.yml#L350-L361)), **the tagged
tree carries a publishable `## X.Y.Z` section** tree carries a publishable `## X.Y.Z` section**
([L353–L365](.github/workflows/release.yml#L353-L365)), and **no published ([L362–L374](.github/workflows/release.yml#L362-L374)), and **no published
release already exists for the tag** release already exists for the tag**
([L366–L381](.github/workflows/release.yml#L366-L381)); any failure ([L375–L390](.github/workflows/release.yml#L375-L390)); any failure
refuses, creating nothing. No `-dev` bump either refuses, creating nothing. No `-dev` bump either
— the fallback does not rewrite main (cast's precedent). Use it when the — the fallback does not rewrite main (cast's precedent). Use it when the
merge path is red, for backfills, and for 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 directly with a backend that is neither `file` nor `package-json`. Fix that
caller. 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 > 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 > direct push refused (branch protection?) — opening the bump PR instead
[L293–L301](.github/workflows/release.yml#L293-L301) — loud, but not a [L302–L310](.github/workflows/release.yml#L302-L310) — loud, but not a
refusal: the post-release `-dev` bump could not push directly, so the run 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 — 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 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 [armed guard's window](#changelog-armed--main-never-sits-disarmed) stays
open. 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. > 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. > 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.
[L347–L350](.github/workflows/release.yml#L347-L350). The message is the [L356–L359](.github/workflows/release.yml#L356-L359). The message is the
remedy. remedy.
> CHANGELOG.md has no '## $VER' section — run changelog-assemble in the release PR before tagging; refusing to publish an empty release > CHANGELOG.md has no '## $VER' section — run changelog-assemble in the release PR before tagging; refusing to publish an empty release
[L359–L365](.github/workflows/release.yml#L359-L365). The tagged tree was [L368–L374](.github/workflows/release.yml#L368-L374). The tagged tree was
never stamped. Assemble the section never stamped. Assemble the section
([docs/CONSUMERS.md](docs/CONSUMERS.md#assembling-a-release-section)), then ([docs/CONSUMERS.md](docs/CONSUMERS.md#assembling-a-release-section)), then
delete and re-push the tag. delete and re-push the tag.
> release '$VER' already exists — refusing to re-release, creating nothing. > release '$VER' already exists — refusing to re-release, creating nothing.
[L366–L381](.github/workflows/release.yml#L366-L381). A published release is [L375–L390](.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 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. 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 The bump belongs to the merge door alone — the tag door deliberately does not
rewrite main ([L316–L320](.github/workflows/release.yml#L316-L320)) — and it rewrite main ([L325–L329](.github/workflows/release.yml#L325-L329)) — and it
runs *after* the tag, the notes and the publish. So a refusal here leaves a 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, 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 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. in this catalog whose remedy is a manual bump, not a re-run.
> version_next_dev: refusing '$ver' — expected bare X.Y.Z > 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 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 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 protection is expected, and the step opens the bump PR itself rather than
failing ([L293–L301](.github/workflows/release.yml#L293-L301)). failing ([L302–L310](.github/workflows/release.yml#L302-L310)).
### Red main that is not the release workflow ### Red main that is not the release workflow