docs: describe all tag-door assertions
All checks were successful
CI / self-guards (pull_request) Successful in 10s
CI / release-exercise (pull_request) Successful in 12s
CI / action-exercise (pull_request) Successful in 6s
CI / docs-sync-exercise (pull_request) Successful in 6s
labels / labels (pull_request) Successful in 9s
CI / test (pull_request) Successful in 3m53s
Refs guard / refs-not-closing (pull_request) Successful in 7s

This commit is contained in:
codex-bot-andresmgsl 2026-08-30 09:33:12 +00:00
parent fe4ec57ff2
commit 1aa03cad77

View file

@ -146,13 +146,15 @@ refusal is the single failure in this file that leaves a real release behind.
- **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#L303-L371)) — publishes the
([release.yml](.github/workflows/release.yml#L316-L401)) — 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 two asserts: **the tag names the
and no label check — what is left is three asserts: **the tag names the
tree's own version**
([L328L339](.github/workflows/release.yml#L328-L339)) and **the tagged
([L341L352](.github/workflows/release.yml#L341-L352)), **the tagged
tree carries a publishable `## X.Y.Z` section**
([L340L352](.github/workflows/release.yml#L340-L352)); either failing
([L353L365](.github/workflows/release.yml#L353-L365)), and **no published
release already exists for the tag**
([L366L381](.github/workflows/release.yml#L366-L381)); 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
@ -503,25 +505,31 @@ 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#L303-L371))
### The tag door refused ([release.yml](.github/workflows/release.yml#L316-L401))
> 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.
[L333L337](.github/workflows/release.yml#L333-L337). The message is the
[L347L350](.github/workflows/release.yml#L347-L350). 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
[L346L349](.github/workflows/release.yml#L346-L349). The tagged tree was
[L359L365](.github/workflows/release.yml#L359-L365). 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
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 bump belongs to the merge door alone — the tag door deliberately does not
rewrite main ([L303L307](.github/workflows/release.yml#L303-L307)) — and it
rewrite main ([L316L320](.github/workflows/release.yml#L316-L320)) — 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