From 1aa03cad77b6396da7ff729639a6ecc5230eaf64 Mon Sep 17 00:00:00 2001 From: codex-bot-andresmgsl Date: Sun, 30 Aug 2026 09:33:12 +0000 Subject: [PATCH] docs: describe all tag-door assertions --- README.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 751dd73..d1bfc00 100644 --- a/README.md +++ b/README.md @@ -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** - ([L328–L339](.github/workflows/release.yml#L328-L339)) and **the tagged + ([L341–L352](.github/workflows/release.yml#L341-L352)), **the tagged tree carries a publishable `## X.Y.Z` section** - ([L340–L352](.github/workflows/release.yml#L340-L352)); either failing + ([L353–L365](.github/workflows/release.yml#L353-L365)), and **no published + release already exists for the tag** + ([L366–L381](.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. -[L333–L337](.github/workflows/release.yml#L333-L337). The message is the +[L347–L350](.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 -[L346–L349](.github/workflows/release.yml#L346-L349). The tagged tree was +[L359–L365](.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. + +[L366–L381](.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 ([L303–L307](.github/workflows/release.yml#L303-L307)) — and it +rewrite main ([L316–L320](.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