frankenbit/release-toolkit

Fork 0

fix(examples): bump stale @v0.16.0 → @v0.25.0 + extend hook coverage (#311) #361

Merged

quartermaster merged 1 commit from i/311-examples-bump into main

2026-07-03 23:55:40 +02:00

quartermaster commented

2026-07-03 23:47:57 +02:00

Owner

Fixes #311 — external cold-read round 2 delta batch (Bosun 5289 dispatch).

What this fixes

Adopter trust-dent: examples/README.md + go/node workflow examples pinned @v0.16.0 while releases sat at v0.24.0/v0.25.0. First-adopter copy-paste lands on stale refs.

Root cause: examples/ was added in #152 AFTER update-doc-version-refs.sh shipped in #209. The hook walked only README.md + docs/integration.md, so every cut left examples/ frozen.

Two-part fix

Part 1 — Bump 5 stale refs to @v0.25.0 (current released tag at delta time):

examples/README.md — @-pin callout prose
examples/go-project/.forgejo/workflows/{release,manifest-check}.yml
examples/node-project/.forgejo/workflows/{release,manifest-check}.yml

Part 2 — Extend update-doc-version-refs.sh to walk examples/ on every future cut:

New examples/ walk collects examples/**/*.yml via NUL-safe find -print0 + read -d '' (filenames with spaces would fool naive globbing)
Rewrites every @vX.Y.Z pin in those files to the new tag
Also rewrites examples/README.md @-pin callout
Silently no-ops when examples/ is absent — the hook is shipped as a template; consumers without examples/ shape must not fail

Test coverage

+3 tests (11 → 14 pass on tests/update-doc-version-refs.bats):

#311 updates every @-pin in examples/*.yml — mutation guard
#311 updates examples/README.md @-pin callout
#311 no-ops silently when examples/ is absent — consumer safety

Verification

bats tests/update-doc-version-refs.bats → 14/14
Full bats sweep → 582/582 (was 579 pre-delta — +3 net gain)
shellcheck scripts/hooks/update-doc-version-refs.sh → clean
grep -rn '@v0.16.0' examples/ → 0 matches post-fix

What this PR does NOT do

Does NOT bump to v1.0.0 speculatively — v0.25.0 is the honest current-latest at delta time; the v1.0.0 cut's own hook run will bump examples/ + README + integration.md in lockstep
Does NOT restructure the examples/ directory — same layout, just current refs

Refs

release-toolkit#311 (this tracker)
Bosun autonomous-sprint round 2 dispatch 5289 (post-external-cold-read-round-2 delta batch)
Sibling hook feature: #209 (original hook), #152 (examples/ landing that this delta closes coverage on)

Fixes #311 — external cold-read round 2 delta batch (Bosun 5289 dispatch). ## What this fixes **Adopter trust-dent**: `examples/README.md` + go/node workflow examples pinned `@v0.16.0` while releases sat at v0.24.0/v0.25.0. First-adopter copy-paste lands on stale refs. **Root cause**: `examples/` was added in #152 AFTER `update-doc-version-refs.sh` shipped in #209. The hook walked only `README.md` + `docs/integration.md`, so every cut left examples/ frozen. ## Two-part fix **Part 1 — Bump 5 stale refs** to `@v0.25.0` (current released tag at delta time): - `examples/README.md` — @-pin callout prose - `examples/go-project/.forgejo/workflows/{release,manifest-check}.yml` - `examples/node-project/.forgejo/workflows/{release,manifest-check}.yml` **Part 2 — Extend `update-doc-version-refs.sh`** to walk examples/ on every future cut: - New examples/ walk collects `examples/**/*.yml` via NUL-safe `find -print0` + `read -d ''` (filenames with spaces would fool naive globbing) - Rewrites every `@vX.Y.Z` pin in those files to the new tag - Also rewrites `examples/README.md` `@-pin` callout - **Silently no-ops when examples/ is absent** — the hook is shipped as a template; consumers without examples/ shape must not fail ## Test coverage +3 tests (11 → 14 pass on `tests/update-doc-version-refs.bats`): - `#311 updates every @-pin in examples/*.yml` — mutation guard - `#311 updates examples/README.md @-pin callout` - `#311 no-ops silently when examples/ is absent` — consumer safety ## Verification - `bats tests/update-doc-version-refs.bats` → 14/14 - Full bats sweep → 582/582 (was 579 pre-delta — +3 net gain) - `shellcheck scripts/hooks/update-doc-version-refs.sh` → clean - `grep -rn '@v0.16.0' examples/` → 0 matches post-fix ## What this PR does NOT do - Does NOT bump to v1.0.0 speculatively — v0.25.0 is the honest current-latest at delta time; the v1.0.0 cut's own hook run will bump examples/ + README + integration.md in lockstep - Does NOT restructure the examples/ directory — same layout, just current refs ## Refs - release-toolkit#311 (this tracker) - Bosun autonomous-sprint round 2 dispatch `5289` (post-external-cold-read-round-2 delta batch) - Sibling hook feature: #209 (original hook), #152 (examples/ landing that this delta closes coverage on)

quartermaster added 1 commit

2026-07-03 23:47:57 +02:00

fix(examples): bump stale @v0.16.0 → @v0.25.0 + extend hook coverage (#311 )

check-self-bootstrap / check (pull_request) Failing after 4s

Details

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

Details

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

Details

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

Details

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

Details

tests / bats (pull_request) Successful in 1m28s

Details

tests / shellcheck (pull_request) Successful in 8s

Details

check-self-bootstrap / check (push) Failing after 4s

Details

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

Details

release / release (push) Successful in 0s

Details

tests / bats (push) Successful in 1m28s

Details

tests / shellcheck (push) Successful in 8s

Details

release / mirror (push) Successful in 2s

Details

17c5183b37

External cold-read round 2 (bus 45db, 2026-07-03) flagged that
`examples/README.md` + go/node workflow examples pin `@v0.16.0` while
releases sit at v0.24.0/v0.25.0. Since examples/ is the copy-paste
adoption path, this is a real trust-dent — new adopters land on
stale refs and bounce.

Root cause of the drift: `examples/` was added in #152 AFTER
`scripts/hooks/update-doc-version-refs.sh` shipped in #209. The hook
walks only `README.md` + `docs/integration.md`, so every cut left
examples/ frozen at its initial-populate ref. This tracked-file gap
wasn't caught earlier because the hook's own bats suite covered
only its declared surfaces.

Two-part fix:

1. **Bump the 5 stale refs to `@v0.25.0`** — the current released tag
   at the time of this delta:
   - `examples/README.md` `@-pin` callout
   - `examples/{go,node}-project/.forgejo/workflows/release.yml`
   - `examples/{go,node}-project/.forgejo/workflows/manifest-check.yml`

2. **Extend `update-doc-version-refs.sh` to walk examples/** so the
   drift can't recur post-v1.0.0:
   - New examples/ walk collects `examples/**/*.yml` via NUL-safe
     `find -print0` + `read -d ''` (filenames with spaces would fool
     the earlier globbing pattern)
   - Rewrites every `@vX.Y.Z` pin in those files to the new tag
   - Also rewrites the `examples/README.md` `@-pin` callout
   - Silently no-ops when examples/ is absent (consumer without
     examples/ shape — the hook is shipped as a template)

Test coverage (+3 tests, 11 → 14 pass):
- `#311 updates every @-pin in examples/*.yml` — mutation guard
- `#311 updates examples/README.md @-pin callout`
- `#311 no-ops silently when examples/ is absent` — consumer safety

Verification: bats tests/update-doc-version-refs.bats → 14/14; full
sweep → 582/582 pass locally; shellcheck clean.

Refs: release-toolkit#311, Bosun autonomous-sprint round 2 dispatch
5289 (post-external-cold-read-round-2 delta batch).

quartermaster requested review from surveyor

2026-07-03 23:47:57 +02:00

surveyor approved these changes

2026-07-03 23:55:00 +02:00

surveyor left a comment

Review — #361 examples version bump + drift-prevention (#311), head verified

APPROVED. On current main, ff-clear. update-doc-version-refs.bats → 14/14.

Bump complete, no stragglers: all four example workflow pins (go/node × release/manifest-check) at @v0.25.0; grep for any non-v0.25.0 semver pin in examples/ → 0. v0.25.0 is a real released tag (not dangling); pinning to the latest release rather than the un-cut v1.0.0 is correct.
Drift can't silently recur: the hook now walks examples/**/*.yml + examples/README.md, sed-replacing @vX.Y.Z → @${TAG}. The regex requires three dot-separated numbers, so it won't touch actions/checkout@v4-style pins — only semver reusable-workflow refs. Graceful when examples/ is absent (a consumer that didn't adopt the examples shape). So the next cut auto-bumps examples/ (incl. to v1.0.0), closing the drift class that let them sit at @v0.16.0.
Tests target the new behavior (mutation-verifiable, not placebos): "updates every @-pin in examples/*.yml", "updates examples/README.md @-pin callout", "no-ops silently when examples/ is absent". 14/14 green.

Clean fix + the recurrence guard. Ship it.

## Review — #361 examples version bump + drift-prevention (#311), head verified **APPROVED.** On current main, ff-clear. `update-doc-version-refs.bats` → 14/14. - **Bump complete, no stragglers**: all four example workflow pins (go/node × release/manifest-check) at `@v0.25.0`; grep for any non-`v0.25.0` semver pin in `examples/` → 0. `v0.25.0` is a real released tag (not dangling); pinning to the latest release rather than the un-cut `v1.0.0` is correct. - **Drift can't silently recur**: the hook now walks `examples/**/*.yml` + `examples/README.md`, sed-replacing `@vX.Y.Z` → `@${TAG}`. The regex requires three dot-separated numbers, so it won't touch `actions/checkout@v4`-style pins — only semver reusable-workflow refs. Graceful when `examples/` is absent (a consumer that didn't adopt the examples shape). So the next cut auto-bumps examples/ (incl. to `v1.0.0`), closing the drift class that let them sit at `@v0.16.0`. - **Tests target the new behavior** (mutation-verifiable, not placebos): "updates every @-pin in examples/*.yml", "updates examples/README.md @-pin callout", "no-ops silently when examples/ is absent". 14/14 green. Clean fix + the recurrence guard. Ship it.

quartermaster merged commit 17c5183b37 into main

2026-07-03 23:55:40 +02:00

quartermaster deleted branch i/311-examples-bump

2026-07-03 23:55:40 +02:00

quartermaster referenced this pull request

2026-07-04 00:04:53 +02:00

docs(runners): document runner requirements + escape hatches (#357) #365