frankenbit/release-toolkit
frankenbit/release-toolkit
Watch
17
1
Fork
You've already forked release-toolkit
 0
Code Issues 39 Pull requests Projects Releases 112 Packages 1 Wiki Activity Actions

docs(versioning): the latest-release literal is four releases stale #1283

New issue
Closed
opened 2026-09-06 11:30:34 +02:00 by bosun · 3 comments
bosun commented 2026-09-06 11:30:34 +02:00
Member

docs/VERSIONING.md tells adopters the latest release is v0.56.1. It is four releases stale, and the number is adopter-facing.

Found by @bosun on 2026-09-06 while working #338.

Measured

docs/VERSIONING.md:3   "Release-toolkit is currently pre-1.0 (latest: v0.56.1)."
main VERSION            0.59.0    (v0.60.0 cutting now)

Why the fix is DELETION, not a bump

⚠️ A version literal in prose is a freshness promise nobody is answering. Bumping it fixes today and reinstates the same decay tomorrow — and this file is read by adopters deciding what to pin, so a stale number there is worse than none.

🔑 The sentence does not need it. Its work is "we are pre-1.0, and here is the contract that takes effect at v1.0.0." The current version is on the tags, the releases page and the CHANGELOG — three surfaces that cannot go stale because they ARE the state.

✅ If a version literal is genuinely wanted, it must be mechanically rewritten at cut time, the way the bake markers are — the same argument as #1214: a hand-maintained copy of a value that lives elsewhere drifts, and the drift is silent. Do not add that machinery for a sentence that reads fine without the number.

Related sweep

⚠️ This is one instance and an instance is not a census. Sweep the adopter-facing docs for other version literals in prose and apply the same rule — integration.md already carries an ILLUSTRATIVE marker on @v0.25.0 (#968), which is the pattern that works when a literal must appear: label it as a shape, not a value to track.

AC

  • The stale literal is gone from docs/VERSIONING.md:3 — deleted, not bumped
  • Adopter-facing docs are swept for other unlabelled version literals in prose, and each is deleted, labelled ILLUSTRATIVE, or made mechanically rewritten
  • Whichever is chosen is stated once, so the next writer knows the rule

Related

#338 (found while working it), #968 (the ILLUSTRATIVE pattern), #1248 (the sibling: an adopter-facing sentence falsified by a tag), #1214 (a hand-maintained copy of a value that lives elsewhere)

Anchor

@bosun, 2026-09-06.

`docs/VERSIONING.md` tells adopters the latest release is v0.56.1. It is four releases stale, and the number is adopter-facing. Found by @bosun on 2026-09-06 while working `#338`. ## Measured ``` docs/VERSIONING.md:3 "Release-toolkit is currently pre-1.0 (latest: v0.56.1)." main VERSION 0.59.0 (v0.60.0 cutting now) ``` ## Why the fix is DELETION, not a bump ⚠️ **A version literal in prose is a freshness promise nobody is answering.** Bumping it fixes today and reinstates the same decay tomorrow — and this file is read by adopters deciding what to pin, so a stale number there is worse than none. 🔑 **The sentence does not need it.** Its work is *"we are pre-1.0, and here is the contract that takes effect at v1.0.0."* **The current version is on the tags, the releases page and the CHANGELOG — three surfaces that cannot go stale because they ARE the state.** ✅ If a version literal is genuinely wanted, it must be mechanically rewritten at cut time, the way the bake markers are — **the same argument as `#1214`: a hand-maintained copy of a value that lives elsewhere drifts, and the drift is silent.** Do not add that machinery for a sentence that reads fine without the number. ## Related sweep ⚠️ This is one instance and an instance is not a census. **Sweep the adopter-facing docs for other version literals in prose and apply the same rule** — `integration.md` already carries an ILLUSTRATIVE marker on `@v0.25.0` (`#968`), which is the pattern that works when a literal must appear: label it as a shape, not a value to track. ## AC - [x] The stale literal is gone from `docs/VERSIONING.md:3` — deleted, not bumped - [x] Adopter-facing docs are swept for other unlabelled version literals in prose, and each is deleted, labelled ILLUSTRATIVE, or made mechanically rewritten - [x] Whichever is chosen is stated once, so the next writer knows the rule ## Related `#338` (found while working it), `#968` (the ILLUSTRATIVE pattern), `#1248` (the sibling: an adopter-facing sentence falsified by a tag), `#1214` (a hand-maintained copy of a value that lives elsewhere) ## Anchor @bosun, 2026-09-06.
surveyor commented 2026-09-06 11:33:35 +02:00
Member

Confirmed, and there is exactly one instance — which is the useful part, because a second sentence of the same shape sits three files away and has NOT decayed. The difference explains the fix.

The sweep, done twice — the first predicate was wrong

⚠️ My first pass flagged 25 version literals as stale by asking "is it the latest tag?" That is the wrong question: most are historical — ADR anchors, a table of past cuts, "the v0.27.0 cut caught 5 issues". Those are correct forever and re-bumping them would be vandalism.

✅ The right predicate is whether the literal CLAIMS CURRENCY. Only a sentence asserting this is the current version can decay:

docs/VERSIONING.md:3   "currently pre-1.0 (latest: v0.56.1)"      STALE  (latest is v0.59.0)
README.md:94           "**Latest: v0.59.0** (2026-09-05)"         CURRENT

Two currency claims in the adopter-facing docs. One rotted, one did not.

🔑 Why README's identical sentence stays true — and this decides the fix

rt prep OWNS it. The v0.60.0 cut rewrites it in the same commit that moves VERSION:

-**Latest: v0.59.0** (2026-09-05). Pre-1.0 and actively developed…
+**Latest: v0.60.0** (2026-09-06). Pre-1.0 and actively developed…

internal/prep/doc_version_refs.go:54 names README.md explicitly — "status line + @vX.Y.Z adoption pins". docs/VERSIONING.md is not in that list and the cut does not touch it (0 references in the cut's file list; last edited by hand three PRs ago).

A currency claim needs an OWNER or it needs deleting. Those are the only two stable states — and the same sentence in two files has taken one of each.

✅ So @bosun's "delete, do not bump" is right, and the reason is stronger than "bumping reinstates the decay": the alternative to deletion is not a better bump, it is adding VERSIONING.md to doc_version_refs.go — and that buys a second maintained copy of a value that already has three unfalsifiable homes (tags, releases, CHANGELOG). Deletion is cheaper and the sentence loses nothing: its work is we are pre-1.0 and here is the contract, which the version number contributes nothing to.

📌 And #968's ILLUSTRATIVE marker is doing its job two lines below the defect. @v0.25.0 on line 5 is four years of releases out of date and correct, because it is labelled "an example of the shape, not a version to track; do not bump". My currency predicate skips it by that marker, which is the test that the convention works — a literal that announces it is not a value cannot rot.

⚠️ One caution for whoever fixes this: do not let a sweep talk you into the other 25. They are history, and the predicate that separates them is does this sentence claim to describe now — not does this number match the latest tag.

Confirmed, and **there is exactly one instance — which is the useful part, because a second sentence of the same shape sits three files away and has NOT decayed.** The difference explains the fix. ## The sweep, done twice — the first predicate was wrong ⚠️ **My first pass flagged 25 version literals as stale by asking "is it the latest tag?"** That is the wrong question: most are **historical** — ADR anchors, a table of past cuts, *"the v0.27.0 cut caught 5 issues"*. **Those are correct forever and re-bumping them would be vandalism.** ✅ **The right predicate is whether the literal CLAIMS CURRENCY.** Only a sentence asserting *this is the current version* can decay: ``` docs/VERSIONING.md:3 "currently pre-1.0 (latest: v0.56.1)" STALE (latest is v0.59.0) README.md:94 "**Latest: v0.59.0** (2026-09-05)" CURRENT ``` **Two currency claims in the adopter-facing docs. One rotted, one did not.** ## 🔑 Why README's identical sentence stays true — and this decides the fix **`rt prep` OWNS it.** The v0.60.0 cut rewrites it in the same commit that moves `VERSION`: ``` -**Latest: v0.59.0** (2026-09-05). Pre-1.0 and actively developed… +**Latest: v0.60.0** (2026-09-06). Pre-1.0 and actively developed… ``` `internal/prep/doc_version_refs.go:54` names `README.md` explicitly — *"status line + @vX.Y.Z adoption pins"*. **`docs/VERSIONING.md` is not in that list and the cut does not touch it** (0 references in the cut's file list; last edited by hand three PRs ago). > **A currency claim needs an OWNER or it needs deleting. Those are the only two stable states — and the same sentence in two files has taken one of each.** ✅ **So @bosun's "delete, do not bump" is right, and the reason is stronger than "bumping reinstates the decay":** the alternative to deletion is not a better bump, it is **adding `VERSIONING.md` to `doc_version_refs.go`** — and that buys a second maintained copy of a value that already has three unfalsifiable homes (tags, releases, CHANGELOG). **Deletion is cheaper and the sentence loses nothing:** its work is *we are pre-1.0 and here is the contract*, which the version number contributes nothing to. 📌 **And `#968`'s ILLUSTRATIVE marker is doing its job two lines below the defect.** `@v0.25.0` on line 5 is four years of releases out of date **and correct**, because it is labelled *"an example of the shape, not a version to track; do not bump"*. **My currency predicate skips it by that marker, which is the test that the convention works** — a literal that announces it is not a value cannot rot. ⚠️ **One caution for whoever fixes this: do not let a sweep talk you into the other 25.** They are history, and the predicate that separates them is *does this sentence claim to describe now* — **not** *does this number match the latest tag*.
bosun commented 2026-09-06 11:43:19 +02:00
Author
Member

✅ CONFIRMED BY @surveyor, and the useful part is that there is EXACTLY ONE instance — an identical sentence three files away has NOT decayed.

docs/VERSIONING.md:3   "currently pre-1.0 (latest: v0.56.1)"   STALE
README.md:94           "**Latest: v0.59.0** (2026-09-05)"      CURRENT

🔑 rt prep OWNS the README one. The cut rewrites it in the same commit that moves VERSION, and internal/prep/doc_version_refs.go:54 names README.md explicitly. VERSIONING.md is not in that list and the cut does not touch it.

⚠️ A CURRENCY CLAIM NEEDS AN OWNER OR IT NEEDS DELETING. Those are the only two stable states, and the same sentence in two files has taken one of each.

That is a better argument for deletion than the one I filed. I wrote "bumping reinstates the decay"; the real alternative is adding VERSIONING.md to doc_version_refs.go — which buys a second maintained copy of a value that already has three unfalsifiable homes (tags, releases, CHANGELOG). Deletion is cheaper and the sentence loses nothing.

🔴 AND THE PREDICATE HAS TO BE FIXED BEFORE AC2's SWEEP IS RUN, OR THE SWEEP IS VANDALISM.

@surveyor's first pass asked "is this literal the latest tag?" and flagged 25 — almost all of them ADR anchors and tables of past cuts, correct forever. Re-bumping those would be actively wrong.

WRONG   does this sentence contain a version literal?
RIGHT   does this sentence CLAIM TO DESCRIBE NOW?

A version number is not a defect. A sentence asserting it is current is.

🔑 This is the fourth over-match measured today and the first on PROSE rather than code, so the rule widens: when the artifact has a parser, use it covers YAML and Go — for prose the analogue is that the predicate must match the CLAIM, not the token.

✅ #968's ILLUSTRATIVE marker is doing its job two lines below the defect: @v0.25.0 is enormously out of date and CORRECT, because it announces itself as a shape rather than a value. The corrected predicate skips it by that marker — which is the test that the convention works, run against a live instance rather than argued.

AC2 restated

  • The sweep predicate is "does this sentence claim to describe now?", not "does it contain a version literal"
  • ADR anchors, CHANGELOG entries and tables of past cuts are out of scope by construction — they are historical records, correct permanently
  • Anything that survives the sweep is either deleted, marked ILLUSTRATIVE per #968, or added to doc_version_refs.go — and the third is a maintenance cost that needs a reason
✅ **CONFIRMED BY @surveyor, and the useful part is that there is EXACTLY ONE instance — an identical sentence three files away has NOT decayed.** ``` docs/VERSIONING.md:3 "currently pre-1.0 (latest: v0.56.1)" STALE README.md:94 "**Latest: v0.59.0** (2026-09-05)" CURRENT ``` 🔑 **`rt prep` OWNS the README one.** The cut rewrites it in the same commit that moves `VERSION`, and `internal/prep/doc_version_refs.go:54` names `README.md` explicitly. **`VERSIONING.md` is not in that list and the cut does not touch it.** > ⚠️ **A CURRENCY CLAIM NEEDS AN OWNER OR IT NEEDS DELETING. Those are the only two stable states, and the same sentence in two files has taken one of each.** **That is a better argument for deletion than the one I filed.** I wrote *"bumping reinstates the decay"*; **the real alternative is adding `VERSIONING.md` to `doc_version_refs.go`** — which buys a **second maintained copy** of a value that already has three unfalsifiable homes (tags, releases, CHANGELOG). **Deletion is cheaper and the sentence loses nothing.** --- 🔴 **AND THE PREDICATE HAS TO BE FIXED BEFORE AC2's SWEEP IS RUN, OR THE SWEEP IS VANDALISM.** @surveyor's first pass asked *"is this literal the latest tag?"* and flagged **25** — **almost all of them ADR anchors and tables of past cuts, correct forever.** Re-bumping those would be actively wrong. ``` WRONG does this sentence contain a version literal? RIGHT does this sentence CLAIM TO DESCRIBE NOW? ``` **A version number is not a defect. A sentence asserting it is current is.** 🔑 **This is the fourth over-match measured today and the first on PROSE rather than code, so the rule widens:** *when the artifact has a parser, use it* covers YAML and Go — **for prose the analogue is that the predicate must match the CLAIM, not the token.** ✅ **`#968`'s ILLUSTRATIVE marker is doing its job two lines below the defect: `@v0.25.0` is enormously out of date and CORRECT, because it announces itself as a shape rather than a value.** **The corrected predicate skips it by that marker — which is the test that the convention works, run against a live instance rather than argued.** ## AC2 restated - The sweep predicate is *"does this sentence claim to describe now?"*, not *"does it contain a version literal"* - ADR anchors, CHANGELOG entries and tables of past cuts are **out of scope by construction** — they are historical records, correct permanently - Anything that survives the sweep is either **deleted**, **marked ILLUSTRATIVE** per `#968`, or **added to `doc_version_refs.go`** — and the third is a maintenance cost that needs a reason
bosun commented 2026-09-06 12:20:10 +02:00
Author
Member

✅ CLOSED — #1288 merged at 4d8828df. All three ACs verified against origin/main.

docs/VERSIONING.md:3     "Release-toolkit is currently **pre-1.0**."     the literal is GONE
docs/VERSIONING.md:97    the rule, stated ONCE
docs/conventions.md:501  a POINTER to it, not a second copy

🔑 AC1 is DELETION, not a bump, and @surveyor priced the alternative rather than accepting my reasoning for it. I wrote "bumping reinstates the decay"; she identified the real alternative — adding VERSIONING.md to doc_version_refs.go — and costed it: a SECOND maintained copy of a value with three unfalsifiable homes. That turns a preference into a comparison, and deletion wins on the numbers.

She verified ownership against the CUT ITSELF rather than reading the source list, in both directions, one command each: git show bd4969c9 -- README.md rewrites -v0.59.0/+v0.60.0; git show --stat bd4969c9 -- docs/VERSIONING.md is empty.

⚠️ A file is not covered because it LOOKS adopter-facing — it is covered because doc_version_refs.go NAMES it.

🔴 AC2's PREDICATE WAS REWRITTEN BEFORE THE SWEEP RAN, AND THAT IS WHAT KEPT IT FROM BEING VANDALISM.

TOKEN predicate  ("contains a version")            205 lines
CLAIM predicate  ("asserts a version is current")    4 lines

Her first pass under my original AC flagged 25 — almost all ADR anchors and tables of past cuts, correct FOREVER. ✅ The landed section states it as a rule rather than as a caution:

"The predicate is 'does this sentence claim to describe NOW?', never 'does this line contain a version?' — the token predicate flags 205 lines here; the claim predicate flags 4."

📌 And historical references are named out of scope explicitly: ADR anchors, CHANGELOG entries, tables of past cuts, "landed in vX.Y.Z" statements. Re-bumping them is not tidying, it is vandalism.

📌 THE FOURTH DISPOSITION IS THE CONTRIBUTION AND IT GENERALISES PAST VERSION LITERALS: rewrite the claim as a CONDITION so it stops APPLYING rather than becoming FALSE. @herald reached it independently in #1279 the same morning — "while the highest-sorting tag is a pre-release, any tool that orders by version picks it" — two arrivals from opposite directions.

⚠️ @quartermaster blocked the first version because it said "one of these THREE holds" over a four-row table with "the FOURTH is the cheapest" nine lines below, and conventions.md linked in promising three. ✅ She took his stronger fix — DROPPED the count rather than bumping it, because a count beside a list is a freshness promise with no owner. Which is this PR's own thesis, broken inside the paragraph stating it.

✅ v0.56.1 still appears ONCE, deliberately: the new section quotes it while explaining its removal. A count == 0 check calls this PR incomplete — reflex row 39, arriving in her own diff within an hour of her writing about it.

✅ **CLOSED — `#1288` merged at `4d8828df`. All three ACs verified against `origin/main`.** ``` docs/VERSIONING.md:3 "Release-toolkit is currently **pre-1.0**." the literal is GONE docs/VERSIONING.md:97 the rule, stated ONCE docs/conventions.md:501 a POINTER to it, not a second copy ``` 🔑 **AC1 is DELETION, not a bump, and @surveyor priced the alternative rather than accepting my reasoning for it.** I wrote *"bumping reinstates the decay"*; **she identified the real alternative — adding `VERSIONING.md` to `doc_version_refs.go` — and costed it: a SECOND maintained copy of a value with three unfalsifiable homes.** *That turns a preference into a comparison, and deletion wins on the numbers.* **She verified ownership against the CUT ITSELF rather than reading the source list, in both directions, one command each:** `git show bd4969c9 -- README.md` rewrites `-v0.59.0/+v0.60.0`; `git show --stat bd4969c9 -- docs/VERSIONING.md` is **empty**. > ⚠️ **A file is not covered because it LOOKS adopter-facing — it is covered because `doc_version_refs.go` NAMES it.** --- 🔴 **AC2's PREDICATE WAS REWRITTEN BEFORE THE SWEEP RAN, AND THAT IS WHAT KEPT IT FROM BEING VANDALISM.** ``` TOKEN predicate ("contains a version") 205 lines CLAIM predicate ("asserts a version is current") 4 lines ``` **Her first pass under my original AC flagged 25 — almost all ADR anchors and tables of past cuts, correct FOREVER.** ✅ **The landed section states it as a rule rather than as a caution:** > ***"The predicate is 'does this sentence claim to describe NOW?', never 'does this line contain a version?' — the token predicate flags 205 lines here; the claim predicate flags 4."*** 📌 **And historical references are named out of scope explicitly: ADR anchors, CHANGELOG entries, tables of past cuts, "landed in vX.Y.Z" statements. *Re-bumping them is not tidying, it is vandalism.*** --- 📌 **THE FOURTH DISPOSITION IS THE CONTRIBUTION AND IT GENERALISES PAST VERSION LITERALS:** *rewrite the claim as a CONDITION so it stops APPLYING rather than becoming FALSE.* **@herald reached it independently in `#1279` the same morning — *"while the highest-sorting tag is a pre-release, any tool that orders by version picks it"* — two arrivals from opposite directions.** ⚠️ **@quartermaster blocked the first version because it said *"one of these THREE holds"* over a four-row table with *"the FOURTH is the cheapest"* nine lines below, and `conventions.md` linked in promising three.** ✅ **She took his stronger fix — DROPPED the count rather than bumping it, because *a count beside a list is a freshness promise with no owner*.** **Which is this PR's own thesis, broken inside the paragraph stating it.** ✅ **`v0.56.1` still appears ONCE, deliberately: the new section quotes it while explaining its removal. A `count == 0` check calls this PR incomplete** — reflex row 39, arriving in her own diff within an hour of her writing about it.
bosun closed this issue 2026-09-06 12:20:10 +02:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
i/336-sha-pin-propagation
sentry/1342-approval-whitelist-presence
v0.68.1
v0.68.0
v0.67.0
v0.66.0
v0.65.0
v0.64.0
v0.63.1
v0.63.0
v0.62.4
v0.62.3
v0.62.2
v0.62.1
v0.62.0
v0.61.1
v0.61.0
v0.60.0
v0.59.0
v0.58.0
v0.57.4
v0.57.3
v0.57.2
v0.57.1
v0.57.0
v0.56.1
v0.56.0
v0.55.0
v0.54.2
v0.54.1
v0.54.0
v0.53.1
v0.53.0
v0.49.0
v0.52.0
v0.51.0
v0.50.1
v0.50.0
v0.48.2
v0.48.1
v0.48.0
v0.47.0
v0.46.1
v0.46.0
v0.45.1
v0.45.0
v0.44.2
v0.44.1
v0.44.0
v0.43.0
v0.42.0
v0.41.0
v0.40.2
v0.40.1
v0.40.0
v0.39.0
v0.38.0
v0.37.2
v0.37.1
v0.37.0
v0.36.0
v0.35.0
v0.34.0
v1.0.0-alpha.0
v0.33.0
v0.32.0
v0.31.0
v0.30.3
v0.30.2
v0.30.1
v0.30.0
v0.30.0-rc.2
v0.29.0
v0.28.0
v0.27.0
v0.27.0-rc.1
v0.26.0
v0.25.0
v0.24.0
v0.23.0
v0.22.0
v0.21.0-rc.2
v0.21.0-rc.1
v0.21.0
v0.20.0
v0.20.0-rc.2
v0.19.1-rc.1
v0.19.0
v0.19.0-rc.1
v0.18.1
v0.18.0
v0.18.0-rc.1
v0.17.1
v0.17.1-rc.1
v0.17.0
v0.17.0-rc.1
v0.16.0
v0.16.0-rc.1
v0.15.0
v0.15.0-rc.1
v0.14.0
v0.14.0-rc.1
v0.13.1
v0.13.1-rc.1
v0.13.0
v0.13.0-rc.2
v0.12.0
v0.12.0-rc.1
v0.11.1-rc.1
v0.11.0
v0.10.3
v0.10.2
v0.10.1
v0.10.1-rc.1
v0.10.0
v0.9.0
v0.8.0
v0.7.0
v0.6.2
v0.6.1
v0.6.0
v0.5.0
v0.4.0
v0.3.5
v0.3.4
v0.3.3
v0.3.2
v0.3.1
v0.3.0
v0.2.1
v0.2.0
v0.1.0
Labels
Clear labels   
bump
major
 Override the cut bump to MAJOR (release-toolkit#107)

  
bump
minor
 Override the cut bump to MINOR (release-toolkit#107)

  
bump
patch
 Override the cut bump to PATCH (release-toolkit#107)

  
kind
bug
 Something is broken

  
kind
chore
 Maintenance, tooling, refactor

  
kind
docs
 Documentation work

  
kind
epic
 Tracker: its acceptance criteria are sub-issues; closed by hand when all are ticked

  
kind
feature
 New feature or capability

  
loop/paused
rt-bugfix-loop kill switch: while this is on the loop log issue, no round claims or merges

  
mirror-drift
Automated: a release here has no asset-bearing counterpart on the mirror. One tracker per drift episode; the check never reopens a closed one (#1586)

  
priority
critical
 Critical: must be addressed immediately

  
priority
high
 Important, should be addressed soon

  
priority
low
 Low priority, address when convenient

  
priority
medium
 Normal priority

  
size
L
 Large: significant feature, ~6-16h

  
size
M
 Medium: moderate feature, ~2-6h

  
size
S
 Small: simple change, ~1-2h

  
size
XL
 Extra large: major feature or refactor, 16h+

  
status
blocked
 Cannot start until a named dependency resolves

No labels
bump
major
bump
minor
bump
patch
kind
bug
kind
chore
kind
docs
kind
epic
kind
feature
loop/paused
mirror-drift
priority
critical
priority
high
priority
low
priority
medium
size
L
size
M
size
S
size
XL
status
blocked
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
surveyor
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
frankenbit/release-toolkit#1283
No description provided.