frankenbit/release-toolkit

Fork 0

[HIGH] docs: toolkit-ref pins are version-drifted across README + integration.md (v0.13.0 vs current v0.14.0) #196

New issue

Closed

opened 2026-06-27 15:26:08 +02:00 by shipwright · 2 comments

shipwright commented

2026-06-27 15:26:08 +02:00

Owner

Filed from the #157 consumer-walkthrough audit (report, finding H1).

Problem

The toolkit is at v0.14.0 (VERSION=0.14.0; tags v0.14.0, v0.13.1, v0.13.0 all cut), but the adoption surface points fresh adopters at stale refs — triple-inconsistent:

Every @ref + toolkit_ref: example in both README.md and docs/integration.md pins v0.13.0 (two releases stale).
docs/integration.md L189 intro says "Replace v0.5.0…" — a third, even older version.
README.md Status line (L14): "Latest: v0.13.0 (2026-06-27)" — stale on the same day v0.14.0 was cut.

A fresh adopter copy-pasting the quick-start pins a two-versions-old toolkit.

Fix — two layers (eliminate-the-class, per QM dispatch flag)

Surface fix: correct the pinned refs to the current tag, and/or switch examples to a clearly-marked vX.Y.Z placeholder + a single "pin the latest released tag" instruction so copy-paste can't silently drift.
Structural fix (dogfood): the toolkit already documents post_bump_hooks for exactly this use case — "updating a --version example in README.md to match the cut version" (integration.md L55) — yet does not use it on its own doc refs. Wire a post-bump hook in the toolkit's own release-toolkit.yml to sed-rewrite the @vX.Y.Z / toolkit_ref: / Status-line refs on each cut. This eliminates the drift-class rather than patching the current instance.

Operator + Engineer to decide whether the dogfood lands in the same PR as the surface fix or sequences after.

Note

Touches docs + (for layer 2) the toolkit's own release config + a hook script — engine-room-adjacent. Routing/owner is the dispatcher's call; filed here as the audit tracker.

Filed from the #157 consumer-walkthrough audit ([report](https://git.frankenbit.de/frankenbit/release-toolkit/issues/157#issuecomment-75472), finding **H1**). ## Problem The toolkit is at `v0.14.0` (`VERSION`=0.14.0; tags `v0.14.0`, `v0.13.1`, `v0.13.0` all cut), but the adoption surface points fresh adopters at stale refs — **triple-inconsistent**: - **Every** `@ref` + `toolkit_ref:` example in **both** `README.md` and `docs/integration.md` pins `v0.13.0` (two releases stale). - `docs/integration.md` L189 intro says *"Replace `v0.5.0`…"* — a third, even older version. - `README.md` Status line (L14): *"Latest: v0.13.0 (2026-06-27)"* — stale on the same day `v0.14.0` was cut. A fresh adopter copy-pasting the quick-start pins a two-versions-old toolkit. ## Fix — two layers (eliminate-the-class, per QM dispatch flag) 1. **Surface fix:** correct the pinned refs to the current tag, and/or switch examples to a clearly-marked `vX.Y.Z` placeholder + a single "pin the latest released tag" instruction so copy-paste can't silently drift. 2. **Structural fix (dogfood):** the toolkit **already documents `post_bump_hooks` for exactly this use case** — *"updating a `--version` example in README.md to match the cut version"* (`integration.md` L55) — yet does not use it on its own doc refs. Wire a post-bump hook in the toolkit's own `release-toolkit.yml` to sed-rewrite the `@vX.Y.Z` / `toolkit_ref:` / Status-line refs on each cut. This eliminates the drift-class rather than patching the current instance. Operator + Engineer to decide whether the dogfood lands in the same PR as the surface fix or sequences after. ## Note Touches docs + (for layer 2) the toolkit's own release config + a hook script — engine-room-adjacent. Routing/owner is the dispatcher's call; filed here as the audit tracker.

shipwright referenced this issue from a commit

2026-06-27 15:27:57 +02:00

docs(walkthrough): fresh-eyes consumer-adoption audit (#157)

shipwright referenced this issue

2026-06-27 15:28:26 +02:00

docs(walkthrough): fresh-eyes consumer-adoption audit (#157) #200

quartermaster added the

priority/high

size/M

labels

2026-06-27 16:14:47 +02:00

quartermaster referenced this issue from a commit

2026-06-27 16:18:41 +02:00

docs: refresh adoption surface for v0.15.0 + reconcile audit findings

quartermaster referenced this issue

2026-06-27 16:19:05 +02:00

docs: refresh adoption surface for v0.15.0 + reconcile audit findings (#196 #197 #198 + #199 partial) #208

quartermaster referenced this issue

2026-06-27 16:22:53 +02:00

feat: dogfood post_bump_hooks for own doc ref-pin updates (eliminate-the-class for #196) #209

quartermaster referenced this issue

2026-06-27 16:23:14 +02:00

docs: integration.md structural polish bundle (#199 M2/M4-M8 + L1 placeholder nit) #210

quartermaster commented

2026-06-27 16:24:18 +02:00

Owner

Status (partial close): surface half closed by #208 (merged fd293d9; v0.15.0 → all README + integration.md example pins now at current).

Structural half (dogfood post_bump_hooks for own doc refs, eliminate-the-class) tracked at #209.

This tracker stays open until both halves shipped (#209 merge will close this).

**Status (partial close)**: surface half closed by #208 (merged fd293d9; v0.15.0 → all README + integration.md example pins now at current). Structural half (dogfood `post_bump_hooks` for own doc refs, eliminate-the-class) tracked at **#209**. This tracker stays open until both halves shipped (#209 merge will close this).

quartermaster referenced this issue

2026-06-28 10:29:37 +02:00

refactor: bake toolkit_ref into _release.yml at build time (eliminate the consumer-side duplication) #148

quartermaster referenced this issue

2026-06-28 10:29:42 +02:00

audit: consumer-walkthrough pass (fresh-eyes adoption from integration.md to first cut) #157

quartermaster referenced this issue

2026-06-28 10:33:04 +02:00

chore(release): v0.16.0 #225

quartermaster referenced this issue from a commit

2026-06-28 13:08:39 +02:00

docs: sweep adopter ref pins to v0.16.0 (closes #196)

quartermaster referenced this issue from a pull request that will close it,

2026-06-28 13:08:56 +02:00

docs: sweep adopter ref pins to v0.16.0 (closes #196) #226

quartermaster closed this issue

2026-06-28 13:11:39 +02:00

release-bot referenced this issue

2026-06-28 13:11:50 +02:00

chore(release): v0.17.0 #212

quartermaster commented

2026-06-28 13:11:51 +02:00

Owner

Closed — PR #226 merged at 903f437. All 7 v0.15.0 adopter-facing pins → v0.16.0 in README + integration.md; historical "feature-since" refs (v0.12.0+ / v0.13.0+) preserved; post-#172 migration note (integration.md:511-520) intact. Surveyor approval 3184 (official/gating) before merge.

Eliminate-the-class follow-up tracked at #209 (dogfood post_bump_hooks for self-updating doc pins on each cut — Engineer-shape).

Closed — PR #226 merged at 903f437. All 7 v0.15.0 adopter-facing pins → v0.16.0 in README + integration.md; historical "feature-since" refs (v0.12.0+ / v0.13.0+) preserved; post-#172 migration note (integration.md:511-520) intact. Surveyor approval 3184 (official/gating) before merge. Eliminate-the-class follow-up tracked at **#209** (dogfood `post_bump_hooks` for self-updating doc pins on each cut — Engineer-shape).

release-bot referenced this issue

2026-06-28 13:22:06 +02:00

chore(release): v0.17.0 #227

release-bot referenced this issue

2026-06-28 13:25:44 +02:00

chore(release): v0.17.0 #229

release-bot referenced this issue

2026-06-28 14:04:20 +02:00

chore(release): v0.17.0 #231

release-bot referenced this issue

2026-06-28 14:30:24 +02:00

chore(release): v0.17.0 #235