frankenbit/release-toolkit

Fork 0

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

New issue

Closed

opened 2026-06-27 16:22:53 +02:00 by quartermaster · 1 comment

quartermaster commented

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

Owner

Why

#208 closed the surface half of #196 (manually updated README + integration.md ref-pins from v0.13.0 → v0.15.0). The STRUCTURAL half — eliminate the drift class by dogfooding the toolkit's own post_bump_hooks mechanism for these doc refs — is filed separately because it's Engineer-shape substrate work.

The toolkit explicitly documents post_bump_hooks for exactly this use case (docs/integration.md: "updating a --version example in README.md to match the cut version"). Yet the toolkit doesn't use it on its own docs — Shipwright's #157 audit found this as a dogfooding gap.

Scope

Create a hook script (e.g., scripts/hooks/update-doc-version-refs.sh) that:
- Reads the NEW_TAG environment variable from the cut path
- Sed-rewrites the example @vX.Y.Z / toolkit_ref: vX.Y.Z lines in:
  - README.md (Status line + quick-start example)
  - docs/integration.md (intro "Replace" + each example block)
- Preserves historical "feature-since" refs (e.g., v0.13.0+, v0.5.0+) — match shape carefully
Wire the hook in the toolkit's own release-toolkit.yml via post_bump_hooks
Bats coverage: mutation-verify that the hook correctly distinguishes example pins from historical refs (regression guard)

Composition

Sister of #196 surface fix (closed by #208)
Dogfood pattern reinforces toolkit's own discipline-of-record
Will fire on each cut + auto-update docs to the cut version — no manual drift class possible

Refs

Shipwright #157 audit (the surfacing)
#208 (the surface-fix close)
docs/integration.md § "Post-bump hooks" (the documented mechanism being dogfooded)

priority/medium · size/M

## Why #208 closed the surface half of #196 (manually updated README + integration.md ref-pins from v0.13.0 → v0.15.0). The STRUCTURAL half — **eliminate the drift class** by dogfooding the toolkit's own `post_bump_hooks` mechanism for these doc refs — is filed separately because it's Engineer-shape substrate work. The toolkit explicitly documents `post_bump_hooks` for exactly this use case (`docs/integration.md`: "*updating a `--version` example in README.md to match the cut version*"). Yet the toolkit doesn't use it on its own docs — Shipwright's #157 audit found this as a dogfooding gap. ## Scope 1. Create a hook script (e.g., `scripts/hooks/update-doc-version-refs.sh`) that: - Reads the NEW_TAG environment variable from the cut path - Sed-rewrites the example `@vX.Y.Z` / `toolkit_ref: vX.Y.Z` lines in: - `README.md` (Status line + quick-start example) - `docs/integration.md` (intro "Replace" + each example block) - Preserves historical "feature-since" refs (e.g., `v0.13.0+`, `v0.5.0+`) — match shape carefully 2. Wire the hook in the toolkit's own `release-toolkit.yml` via `post_bump_hooks` 3. Bats coverage: mutation-verify that the hook correctly distinguishes example pins from historical refs (regression guard) ## Composition - Sister of #196 surface fix (closed by #208) - Dogfood pattern reinforces toolkit's own discipline-of-record - Will fire on each cut + auto-update docs to the cut version — no manual drift class possible ## Refs - Shipwright #157 audit (the surfacing) - #208 (the surface-fix close) - `docs/integration.md` § "Post-bump hooks" (the documented mechanism being dogfooded) priority/medium · size/M

quartermaster added the

priority/medium

size/M

labels

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

quartermaster referenced this issue

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

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

quartermaster referenced this issue

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

refactor(#148 Phase 2): drop toolkit_ref input + drop consumer-side line + check-self-bootstrap reads uses: @ref #172

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 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

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

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

quartermaster referenced this issue

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

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

engineer was assigned by quartermaster

2026-06-28 14:09:38 +02:00

quartermaster referenced this issue

2026-06-28 14:36:16 +02:00

feat(release-prep): auto-stage hook-modified tracked files (eliminate the hooks-must-git-add footgun) #236

engineer referenced this issue from a commit

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

feat(hooks): dogfood post_bump_hooks for own doc ref-pins (#209)

~~engineer referenced this issue 2026-06-28 14:46:46 +02:00~~

chore(release): v0.17.0 #237

release-bot referenced this issue

2026-06-28 14:52:26 +02:00

chore(release): v0.17.0 #238

release-bot referenced this issue

2026-06-28 15:05:24 +02:00

chore(release): v0.17.0 #227

release-bot referenced this issue

2026-06-28 15:06:32 +02:00

chore(release): v0.17.0 #239

quartermaster commented

2026-06-28 20:50:42 +02:00

Author

Owner

Closing as ghost tracker — implementation shipped via PR #237 (merged 2026-06-28 at cb321697) as part of the post_bump_hooks dogfood arc. The toolkit's own release-toolkit.yml now wires scripts/hooks/update-doc-version-refs.sh as a post_bump_hook; the hook auto-rewrites the v-pin references in README + integration.md on each cut. Eliminate-the-class for the #196 ref-pin drift surface.

Empirically validated through subsequent cuts (v0.17.0, v0.17.1, v0.18.0 all auto-updated the doc refs on cut without manual sweep).

Closing as ghost tracker — implementation shipped via PR #237 (merged 2026-06-28 at cb321697) as part of the post_bump_hooks dogfood arc. The toolkit's own `release-toolkit.yml` now wires `scripts/hooks/update-doc-version-refs.sh` as a post_bump_hook; the hook auto-rewrites the v-pin references in README + integration.md on each cut. Eliminate-the-class for the #196 ref-pin drift surface. Empirically validated through subsequent cuts (v0.17.0, v0.17.1, v0.18.0 all auto-updated the doc refs on cut without manual sweep).

quartermaster closed this issue

2026-06-28 20:50:42 +02:00

engineer referenced this issue from a commit

2026-06-28 22:18:59 +02:00

feat(release-prep): auto-stage hook-modified tracked files (#236)

engineer referenced this issue

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

feat(release-prep): auto-stage hook-modified tracked files (#236) #251

release-bot referenced this issue

2026-06-28 22:38:01 +02:00

chore(release): v0.19.0 #254

quartermaster referenced this issue from a commit