docs: strip the tag inventory; a verified fact still has a shelf life

v0.1.0-rc3 no longer exists anywhere -- not local, not gh, not origin, not
gitea. Verified here independently before changing anything; the releases are
untouched (rc1, rc2, and there never was an rc3 release).

THREE MEASUREMENTS OF ONE FACT IN ONE SESSION, and only the first was careless:

  1. present on all three remotes and locally  (from aa4e901's commit message)
  2. on gh alone                               (git ls-remote, this branch)
  3. nowhere at all                            (git ls-remote, now)

Reading 1 was asserted rather than asked, and correcting it was right. Readings
2 and 3 were each taken correctly, by two different people, and they disagree --
because the tag was deleted in between. So the lesson this section reached for
was too weak. It is not "ask rather than assert"; it is that A REMOTE-SHAPED
FACT HAS A SHELF LIFE EVEN AFTER YOU ASK. A verified answer decays, and prose
cannot distinguish a stale line from a live one, so a reader following
RELEASING.md at 2am has no way to tell which they are holding.

WHAT CHANGES. The present-tense inventory goes, everywhere I put it:
RELEASING.md's "It is on gh only; origin and gitea carry rc1 and rc2", the same
clause's "the mirrors did not agree", tooling.md's "rc3 is on gh alone", and
"pushed to gh" in both tooling.md and the script header -- that last one named a
specific remote too, and we do not actually know which remotes the push reached.
rc3 survives as a plainly historical example: it was pushed while every crate
still said 0.1.0-rc2, dist refused, no release was built. Nothing about where it
is now.

WHAT STAYS. The instruction to ask -- `git tag -l`, `git ls-remote --tags
<remote>` -- because that is the part that ages well: it tells the reader to
look rather than to believe. And the record that aa4e901's claim was wrong when
checked, which is durable precisely because its subject is a fixed text. Note
which half of the earlier correction survived and which did not: "the commit
message was wrong" is permanent; "the tag is on gh alone" was true and is now
false. The keeper is the one whose subject cannot change.

Both files now say explicitly that they record no inventory, so the next editor
knows the absence is deliberate rather than an omission to helpfully fill in.

The principle never decayed and is untouched: a wrong tag is left dead and the
next version cut; a published tag is not moved.

No version bumped, no tag cut, no tag deleted by me.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
This commit is contained in:
Edward Langley
2026-09-21 22:42:00 -07:00
parent d8eca0f0af
commit 7d12ada45d
3 changed files with 37 additions and 21 deletions
+8 -8
View File
@@ -60,12 +60,12 @@ moved. Every step below exists to put that check before the irreversible one.
already public, and a published tag that changes meaning is worse than one that
never built. Bump to the next version, commit, run the preflight, and tag that.
`v0.1.0-rc3` is the standing example — pushed to `gh` while every crate still
said `0.1.0-rc2`, so `dist` refused and the four jobs behind `plan` skipped. It
has no GitHub release and is left as it is. (It is on `gh` **only**; `origin`
and `gitea` carry `rc1` and `rc2`. Check with `git ls-remote --tags <remote>`
rather than assuming the mirrors agree — they did not.)
The worked example is `v0.1.0-rc3`: it was pushed while every crate still said
`0.1.0-rc2`, `dist` refused, and the four jobs behind `plan` skipped. No release
was ever built from it.
A tag with no release is not a tag to clean up on the way to cutting one;
whether the stale `rc` tags are ever removed is a separate decision, and not a
step here.
**Ask which tags exist; do not trust a document that tells you.** `git tag -l`,
and `git ls-remote --tags <remote>` for each remote you push to. Which tags are
where is a fact with a shelf life — it changed twice while this file was being
written — so this file deliberately records no inventory of it. Cleaning up a
dead tag is a separate decision and is not a step in cutting a release.