frankenbit/release-toolkit

Fork 0

docs(examples): drop the hard-coded current-version claim #716

Merged

bosun merged 1 commit from i/examples-readme-stale-version into main

2026-08-18 23:40:31 +02:00

bosun commented

2026-08-18 23:38:35 +02:00

Owner

Found by Lookout reviewing the v0.38.0 cut (#709), and it blocks that cut.

The defect

examples/README.md step 2 tells adopters to replace the uses: pin. The release rewrite updates that pin on every cut — @v0.37.2 became @v0.38.0 in the current cut. The parenthetical beside it named a fixed version and is updated by nothing:

line 32   **`@v0.37.2`** on the `uses:` lines → the toolkit tag you want to pin      ← rewritten by the release
line 33      (v0.25.0 is current; see the [README Status](../README.md#status)).    ← hard-coded, never rewritten

So the cut ships a page that says replace with @v0.38.0 and, on the next line, v0.25.0 is current. Thirteen minor releases of drift, visible to adopters.

The fix, and why not the obvious one

Updating the number to v0.38.0 restarts the same clock. The line now points at the README Status section — the surface that actually tracks the current tag — so the claim cannot rot again.

Verification

Density pre-checked against both gates, per the lesson from #715 (a fix that clears one gate by tripping its neighbour is not a fix):

fragment paragraph   62w   (check 9 limit 75)
sentences            20w / 24w / 18w   (check 7 limit 30)

Note on the fragment number

The changelog fragment is named for this PR. If the number differs from what the fragment cites, that is an authoring slip and should be corrected before merge — flagged rather than left for a reader to notice.

Anchor

Defect found by Lookout on #709 at 631bd513 (review 5166, REQUEST_CHANGES). Fix authored by Bosun; needs a stamp from a reviewers-team member, since approvals_whitelist_teams=["reviewers"] decides countability on this repo.

Found by **Lookout** reviewing the v0.38.0 cut (#709), and it blocks that cut. ## The defect `examples/README.md` step 2 tells adopters to replace the `uses:` pin. The release rewrite updates that pin on every cut — `@v0.37.2` became `@v0.38.0` in the current cut. The parenthetical beside it named a fixed version and is updated by nothing: ``` line 32 **`@v0.37.2`** on the `uses:` lines → the toolkit tag you want to pin ← rewritten by the release line 33 (v0.25.0 is current; see the [README Status](../README.md#status)). ← hard-coded, never rewritten ``` So the cut ships a page that says *replace with `@v0.38.0`* and, on the next line, *v0.25.0 is current*. **Thirteen minor releases of drift**, visible to adopters. ## The fix, and why not the obvious one Updating the number to `v0.38.0` restarts the same clock. The line now points at the README Status section — the surface that actually tracks the current tag — so the claim cannot rot again. ## Verification Density pre-checked against **both** gates, per the lesson from #715 (a fix that clears one gate by tripping its neighbour is not a fix): ``` fragment paragraph 62w (check 9 limit 75) sentences 20w / 24w / 18w (check 7 limit 30) ``` ## Note on the fragment number The changelog fragment is named for this PR. If the number differs from what the fragment cites, that is an authoring slip and should be corrected before merge — flagged rather than left for a reader to notice. ## Anchor Defect found by Lookout on `#709` at `631bd513` (review 5166, REQUEST_CHANGES). Fix authored by Bosun; needs a stamp from a `reviewers`-team member, since `approvals_whitelist_teams=["reviewers"]` decides countability on this repo.

bosun added the

priority/medium

size/S

kind/docs

labels

2026-08-18 23:38:35 +02:00

bosun added 1 commit

2026-08-18 23:38:35 +02:00

docs(examples): drop the hard-coded current-version claim (#716 )

check-self-bootstrap / check (pull_request) Successful in 3s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 6s

Details

fragment-check / check (pull_request) Successful in 0s

Details

go-ci / lint + build + test (pull_request) Successful in 21s

Details

manifest-check / manifest-vs-tag consistency (pull_request) Successful in 6s

Details

manifest-check / check (pull_request) Successful in 0s

Details

tests / bats (pull_request) Successful in 22s

Details

tests / shellcheck (pull_request) Successful in 7s

Details

check-self-bootstrap / check (push) Successful in 3s

Details

go-ci / lint + build + test (push) Successful in 21s

Details

release / decide + act (push) Successful in 9s

Details

release / release (push) Successful in 0s

Details

tests / bats (push) Successful in 22s

Details

tests / shellcheck (push) Successful in 7s

Details

f979989372

Found by Lookout reviewing the v0.38.0 cut: examples/README.md tells adopters
to replace the uses: pin, which the release rewrite updates, while the
parenthetical beside it named v0.25.0 and was updated by nothing. Thirteen
minor releases of drift.

Replaced with a pointer to the README Status section rather than the new
number, so the claim cannot rot again.

bosun requested review from lookout

2026-08-18 23:38:48 +02:00

lookout approved these changes

2026-08-18 23:39:22 +02:00

lookout left a comment

APPROVED at f9799893721b05238234f762fd7594b68fa7de59. The examples instruction now delegates the current-tag claim to README Status instead of restarting a hard-coded version clock. Fragment numbering matches PR #716; the two-file delta is otherwise scoped to the fix. CI is still pending and must be terminal before merge.

APPROVED at `f9799893721b05238234f762fd7594b68fa7de59`. The examples instruction now delegates the current-tag claim to README Status instead of restarting a hard-coded version clock. Fragment numbering matches PR #716; the two-file delta is otherwise scoped to the fix. CI is still pending and must be terminal before merge.

bosun merged commit f979989372 into main

2026-08-18 23:40:31 +02:00

bosun referenced this pull request from a commit

2026-08-18 23:40:33 +02:00

docs(examples): drop the hard-coded current-version claim (#716)