[MED] docs: integration.md adoption-surface polish (structure, step-completeness, token clarity) — #157 bundle #199
Labels
No labels
bump
major
bump
minor
bump
patch
kind/bug
kind/chore
kind/docs
kind/feature
priority/critical
priority/high
priority/low
priority/medium
size/L
size/M
size/S
size/XL
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit#199
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Filed from the #157 consumer-walkthrough audit (report). Bundles the MED/LOW adoption-surface findings that don't warrant standalone trackers (H1/H2/M1 are filed separately). Each is a small, independent doc edit; grouped so a single integration.md-polish PR can land them together.
Findings
M2 — "Four-step adoption" Step 1 balloons into ~150 lines of advanced config before Step 2.
post_bump_hooks,section_format, tag-is-version mode, and the hook trust-model all sit 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 an "Advanced configuration" section after the four steps.M3 — "Three consumer-side files" but only two reusable-wrappers shown. L189 claims three thin-wrappers-around-a-reusable, but only
release.yml+manifest-check.ymlare shown (deploy-on-publish is explicitly not a toolkit reusable, L268). Likely a fossil from the retired_release-publish.yml(L302). Fix: correct the count to two, or enumerate the intended third.M4 —
CHANGELOG.mdcreation lives only in Prerequisites, not the numbered steps. A verbatim four-step follower createschangelog.d/(Step 2) but neverCHANGELOG.md(only in Prereqs L23), whichrelease-prep.shreads the current version from. Fix: add "createCHANGELOG.mdwith## [Unreleased]" as an explicit step 0.M5 —
secrets: inheritpresented only as a ~10-line inline YAML comment, never a step (companion to H2). The most load-bearing line is buried in comment text a copy-paster can strip. Fix: elevate to a numbered step/prerequisite.M6 — Forward-references before definition (writer's curse).
path-γ/path (α)/ "ADR-0007 fallback" appear in the Step-3 secrets comment (L229) but aren't defined until L457+ (~230 lines later); "rolling PR" / "manifest-check" used before explained. Fix: one-line gloss or forward-link at first use.M7 — Local dry-run hard-requires an
originremote (terse exit 1).release-prep.sh --dry-runon a fresh local repo with nooriginexits 1 ("no git remote 'origin' configured") after correctly transitioning CHANGELOG + bumping VERSION and touching nothing remote; a bogus/unreachable origin clears it. The docs frame dry-run as workflow-context only (L387), so there's no blessed local-preview path. Fix: either don't hard-require origin in dry-run (owner/repo are only echoed in dry-run, not called), or document that dry-run still needsoriginset. (This one is a small script-or-docs call — engine-room-adjacent; flag for Engineer if the script path is chosen.)M8 — Token-name sprawl, where/permissions split across sections. Three token names cross the surface —
FORGEJO_TOKEN(env forsetup-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 —
runs_onplaceholder convention is mixed:go(literal+comment) vs<YOUR-LABEL>(L289). Pick one.L2 —
bump_overridedefault differs across surfaces: READMEdefault: autovs integration.mddefault: ''. Both accepted byrelease-prep.sh, so harmless — align them.Ref
secrets: inherit— both overstate it (RECOMMENDED, not required) #197Status (partial close): easy-wins (M3, L1, L2) closed by #208 (merged
fd293d9).Remaining items (M2, M4, M5, M6, M7, M8 + Surveyor cab3's L1 placeholder nit) tracked at #210 as a focused Herald (narrative-craft) or Engineer (M7 script call) pass.
This tracker stays open until all 9 items shipped (#210 merge will close this).
quartermaster referenced this issue2026-06-28 10:33:06 +02:00
Closed — integration.md adoption-surface polish complete in two waves: #208 (easy wins: M3 three→two files, L1 partial, L2 bump_override default) + #212 (structural: M2/M4-M8 + L1 placeholder nit final). #212 merged at
3ba7b253.Sibling open: #214 (tmux-tell internal-refs scrub from integration.md — Herald-shape, complementary to this bundle, Surveyor 5143 noted as a deferred follow-up).