frankenbit/release-toolkit

Fork 0

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

New issue

Closed

opened 2026-06-27 16:23:14 +02:00 by quartermaster · 1 comment

quartermaster commented

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

Owner

Why

#208 closed the easy-wins half of #199 (M3 three→two consumer-side files, L1 partial, L2 bump_override default). The remaining items are larger structural docs reworks — better suited for a focused Herald (narrative-craft) or Engineer (M7 script call) pass.

Items

M2 — Four-step adoption Step 1 balloons into ~150 lines of advanced config.

post_bump_hooks, section_format, tag-is-version mode, hook trust-model all inside Step 1 (L49–176).
A linear first-time reader can't tell required-for-first-cut from advanced-optional.
Fix: move advanced knobs to a separate "Advanced configuration" section after the four steps.

M4 — CHANGELOG.md creation lives only in Prerequisites, not the numbered steps.

A verbatim four-step follower creates changelog.d/ (Step 2) but never CHANGELOG.md (only in Prereqs L23), which release-prep.sh reads.
Fix: add "create CHANGELOG.md with ## [Unreleased]" as an explicit step 0 or in Step 2.

M5 — secrets: inherit numbered step elevation.

Currently inline YAML comment (partially covered by #197/#208 reframe).
Most load-bearing line buried where a copy-paster can strip it.
Fix: elevate to a numbered step / explicit prerequisite.

M6 — Forward-references before definition (writer's curse).

path-γ / path (α) / "ADR-0007 fallback" appear in Step-3 secrets comment (L229) but aren't defined until L457+.
"rolling PR" / "manifest-check" used before explained.
Fix: one-line gloss or forward-link at first use.

M7 — Local dry-run hard-requires an origin remote (terse exit 1).

release-prep.sh --dry-run on a fresh local repo with no origin exits 1 ("no git remote 'origin' configured") after CHANGELOG transition + VERSION bump.
Docs frame dry-run as workflow-context only (L387); no blessed local-preview path.
Fix: either don't hard-require origin in dry-run (owner/repo only echoed in dry-run, not called), or document that dry-run still needs origin set.
Note: engine-room-adjacent — script-or-docs call. Engineer-shape if the script path is chosen.

M8 — Token-name sprawl, where/permissions split across sections.

FORGEJO_TOKEN (env for setup-bump-labels.sh, L360), RELEASE_TOOLKIT_TOKEN (repo secret for path-α, L489), secrets.GITHUB_TOKEN (auto-provided alias, L570) — each set in a different place/scope/section.
Fix: one consolidated "Tokens & permissions" table (name · where set · scope · when needed).

L1 (placeholder convention nit per Surveyor cab3):

#208 unified L293 runs-on: from <YOUR-LABEL> to literal go # YOUR Forgejo runner label.
Surveyor's review nit: "go" is frankenbit's specific runner label; in public adoption docs a consumer copying it gets a non-matching value. Generic placeholder (<your-runner-label>) reads less leaky.
Fix: pick a single convention — likely lowercase placeholder for standalone example blocks + literal go only in toolkit-wrapper examples (where the consumer adapts the whole block).

Composition

Sister of #196 + #197 + #198 (all #157 walkthrough audit follow-ups)
Herald-shape: M2/M4/M5/M6/M8 are narrative-craft restructuring
Engineer-shape: M7 may need a script fix (release-prep.sh dry-run origin handling)

Refs

Shipwright #157 audit report
Surveyor cab3 review on #208 (the L1 nit framing)
#208 (the easy-wins close)

priority/medium · size/M

## Why #208 closed the easy-wins half of #199 (M3 three→two consumer-side files, L1 partial, L2 bump_override default). The remaining items are larger structural docs reworks — better suited for a focused Herald (narrative-craft) or Engineer (M7 script call) pass. ## Items **M2 — Four-step adoption Step 1 balloons into ~150 lines of advanced config.** - `post_bump_hooks`, `section_format`, tag-is-version mode, hook trust-model all inside Step 1 (L49–176). - A linear first-time reader can't tell required-for-first-cut from advanced-optional. - **Fix**: move advanced knobs to a separate "Advanced configuration" section after the four steps. **M4 — `CHANGELOG.md` creation lives only in Prerequisites, not the numbered steps.** - A verbatim four-step follower creates `changelog.d/` (Step 2) but never `CHANGELOG.md` (only in Prereqs L23), which `release-prep.sh` reads. - **Fix**: add "create `CHANGELOG.md` with `## [Unreleased]`" as an explicit step 0 or in Step 2. **M5 — `secrets: inherit` numbered step elevation.** - Currently inline YAML comment (partially covered by #197/#208 reframe). - Most load-bearing line buried where a copy-paster can strip it. - **Fix**: elevate to a numbered step / explicit prerequisite. **M6 — Forward-references before definition (writer's curse).** - `path-γ` / `path (α)` / "ADR-0007 fallback" appear in Step-3 secrets comment (L229) but aren't defined until L457+. - "rolling PR" / "manifest-check" used before explained. - **Fix**: one-line gloss or forward-link at first use. **M7 — Local dry-run hard-requires an `origin` remote (terse exit 1).** - `release-prep.sh --dry-run` on a fresh local repo with no `origin` exits 1 ("no git remote 'origin' configured") *after* CHANGELOG transition + VERSION bump. - Docs frame dry-run as workflow-context only (L387); no blessed local-preview path. - **Fix**: either don't hard-require origin in dry-run (owner/repo only echoed in dry-run, not called), or document that dry-run still needs `origin` set. - **Note**: engine-room-adjacent — script-or-docs call. Engineer-shape if the script path is chosen. **M8 — Token-name sprawl, where/permissions split across sections.** - `FORGEJO_TOKEN` (env for `setup-bump-labels.sh`, L360), `RELEASE_TOOLKIT_TOKEN` (repo secret for path-α, L489), `secrets.GITHUB_TOKEN` (auto-provided alias, L570) — each set in a different place/scope/section. - **Fix**: one consolidated "Tokens & permissions" table (name · where set · scope · when needed). **L1 (placeholder convention nit per Surveyor cab3)**: - #208 unified L293 `runs-on:` from `<YOUR-LABEL>` to literal `go # YOUR Forgejo runner label`. - Surveyor's review nit: "go" is frankenbit's specific runner label; in public adoption docs a consumer copying it gets a non-matching value. Generic placeholder (`<your-runner-label>`) reads less leaky. - **Fix**: pick a single convention — likely lowercase placeholder for standalone example blocks + literal `go` only in toolkit-wrapper examples (where the consumer adapts the whole block). ## Composition - Sister of #196 + #197 + #198 (all #157 walkthrough audit follow-ups) - Herald-shape: M2/M4/M5/M6/M8 are narrative-craft restructuring - Engineer-shape: M7 may need a script fix (release-prep.sh dry-run origin handling) ## Refs - Shipwright #157 audit report - Surveyor cab3 review on #208 (the L1 nit framing) - #208 (the easy-wins close) 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:21 +02:00

[MED] docs: integration.md adoption-surface polish (structure, step-completeness, token clarity) — #157 bundle #199

herald was assigned by quartermaster

2026-06-27 17:15:59 +02:00

~~herald referenced this issue 2026-06-27 17:26:48 +02:00~~

chore(release): v0.17.0 #212

herald referenced this issue from a commit

2026-06-27 17:26:49 +02:00

docs(integration): structural polish bundle (#210)

quartermaster referenced this issue

2026-06-27 17:35:53 +02:00

docs: scrub remaining tmux-tell internal-refs from integration.md (out-of-scope leak from #210) #214

quartermaster referenced this issue

2026-06-27 17:36:06 +02:00

eng: evaluate release-prep.sh dry-run origin-remote requirement (#199 M7 Engineer-side follow-up) #216

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

herald referenced this issue from a commit

2026-06-28 13:18:49 +02:00

docs(integration): structural polish bundle (#210)

quartermaster commented

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

Author

Owner

Closed — PR #212 merged at 3ba7b253. Herald's structural polish bundle (M2/M4-M8 + L1 placeholder nit) shipped; sharp recovery from the #226-vs-#212 conflict via per-step reconstruction onto #226's clean base. Surveyor 5143 verified deep at source (the toolkit_ref discrepancy traced + resolved: 3 matches were in the #172 retirement note, not consumer-input lines).

Sibling close: #199 (integration.md adoption-surface polish) — #208 shipped the easy-wins half, #212 the structural half. Closing #199 as well in a separate comment.

Remaining audit tail: Surveyor's int-1/2/3 follow-up from #158 applies against #212's final structure now that the rebase landed.

Closed — PR #212 merged at 3ba7b253. Herald's structural polish bundle (M2/M4-M8 + L1 placeholder nit) shipped; sharp recovery from the #226-vs-#212 conflict via per-step reconstruction onto #226's clean base. Surveyor 5143 verified deep at source (the toolkit_ref discrepancy traced + resolved: 3 matches were in the #172 retirement note, not consumer-input lines). Sibling close: **#199** (integration.md adoption-surface polish) — #208 shipped the easy-wins half, #212 the structural half. Closing #199 as well in a separate comment. Remaining audit tail: Surveyor's int-1/2/3 follow-up from #158 applies against #212's final structure now that the rebase landed.

quartermaster closed this issue

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