Skip to content

Commit d3e244d

Browse files
dmealingclaude
andcommitted
docs(releasing): the tag gate's real refusal list, and why --sat-out is corroborated
The enumerated list omitted the llms-mirror gate and the fetch-failure refusal, so an operator blocked by either would find no remedy in the release procedure. It also now states the rule that makes --sat-out safe rather than dangerous: the flag is checked against the port manifests, not taken on trust. An earlier version printed it as a ready-made remedy for any mismatch, which would have waived the defect the gate exists to catch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NynrRND6ZUwGvq3ZUTCfxG
1 parent c37c5c0 commit d3e244d

1 file changed

Lines changed: 19 additions & 8 deletions

File tree

‎docs/RELEASING.md‎

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -168,16 +168,27 @@ Publish in tier order so a dependent never lands before its dependency. **`forge
168168
bun scripts/finish-release.mjs <version> --check # gates only
169169
```
170170

171-
It refuses to tag a tree that does not state the release: dirty or unpushed tree, a tag
172-
that already exists (never move one — a moved tag silently changes what the site
173-
deploys), payload coordinates that disagree with what shipped, a missing injector or
174-
payload, or a tag the deploy's own filter would not resolve. A registry that genuinely
175-
**sat out** the release under publish-what-changed is declared explicitly
176-
(`--sat-out pypi,nuget`) rather than guessed — guessing "sat out" ships the stale
177-
number, and guessing "published" blocks a correct lagging registry. **npm can never sit
178-
out:** `<version>` *is* the npm version, so a mismatch there always means
171+
It refuses to tag a tree that does not state the release: a dirty or unpushed tree, a
172+
**failed `git fetch`** (which makes the sync claim unverifiable, so it is a refusal
173+
rather than a tick), a tag that already exists (never move one — a moved tag silently
174+
changes what the site deploys), payload coordinates that disagree with what shipped, a
175+
missing injector / payload / `site-reference/`, **llms mirrors naming a version this
176+
release did not ship on any line that makes a registry claim**, or a tag the deploy's
177+
own filter would not resolve.
178+
179+
A registry that genuinely **sat out** the release under publish-what-changed is declared
180+
(`--sat-out pypi,nuget`) rather than guessed — guessing "sat out" ships the stale number,
181+
and guessing "published" blocks a correct lagging registry. **npm can never sit out:**
182+
`<version>` *is* the npm version, so a mismatch there always means
179183
`bun run site:payload` was not re-run.
180184

185+
**`--sat-out` is corroborated, not believed.** A registry that truly sat out has an
186+
UNMOVED manifest (`pyproject.toml`, `Directory.Build.props`, the reactor pom); a payload
187+
that was simply not rebuilt sits beside a manifest that DID move, and declaring that one
188+
`--sat-out` is refused with the manifest quoted back. This matters because an earlier
189+
version printed the flag as a ready-made remedy for any mismatch — which would have
190+
waived the exact defect the gate exists to catch.
191+
181192
**A second effect, and it is an improvement rather than a cost.** `conformance.yml` and
182193
`integration-tests.yml` are the heavy gates that run on a `v*` tag and nowhere else.
183194
Cutting the tag last means they now run against the FINAL coordinated tree — all four

0 commit comments

Comments
 (0)