docs(integration): the cut walkthrough named retired bash scripts (#713 PR 1 of 3) #736

Merged

bosun merged 4 commits from i/713-adopter-docs-bash-path into main 2026-08-19 09:16:41 +02:00

Conversation 2 Commits 4 Files changed 6 +65 -56

herald commented 2026-08-19 08:26:46 +02:00

Owner

Copy link

PR 1 of 3 on #713 — the adopter-facing half. Graded on one question: does an adopter following this succeed?

#607 and #705 retired the bash orchestrators. The docs kept describing them in the present tense, in the files an adopter actually follows.

Mapping, derived from reusable-release.yml rather than guessed

release-decide.sh  → rt decide
release-prep.sh    → rt prep
draft-release.sh   → rt release

⚠️ A mechanical derivation gets these three wrong. Matching basename against cmd/rt/*.go returns "no direct subcommand" for exactly these — the port renamed them — while succeeding on the eleven whose names survived. The method works everywhere it does not matter.

Changed

file	what
docs/integration.md	35 lines — the cut walkthrough, tag-creation sequence, dry-run section, idempotency, bump-override
docs/events-logging.md	6 — the event→emitter table
docs/architecture/branch-strategy.md	4 — line-number citations into deleted files, numbers dropped rather than repointed
docs/operations.md	4 — present-tense mechanism claims only
.forgejo/workflows/release.yml	2 — its header calls it "the same pattern external adopters wire in their own repo", so its comments are adopter docs in YAML

integration.md:110 was a citation with no successor: it pinned the Python-yq requirement to scripts/lib/config.sh:20. The requirement is still real — scripts/lib/forgejo-api.sh still shells out to yq -r — so this is a repoint, not a deletion.

⛔ Deliberately NOT changed — the tense discriminator

Same filename, opposite dispositions. "the Go port of X.sh" is permanently true; "X.sh does Y" is false the moment X.sh is deleted.

• operations.md bug narratives — "both release-prep.sh and draft-release.sh were logging…". Rewriting these would be false: rt prep never had those bugs.
• fragment-style.md, all 6 — inside fenced ```markdown before/after blocks quoting real past entries. Rewriting falsifies the illustration.
• integration.md:870 — the v0.5.0–v0.22.0 sidecar history. ⚠️ One paragraph contains both: the historical mention stays, the "draft-release.sh ignores it" two clauses later is present tense and was changed.
• ADRs (71 lines / 9 files), CHANGELOG.md, changelog.d/ — PR 3 and never, respectively.

Held for a ruling, not silently skipped

• VERSIONING.md names retired scripts as the public CLI compat surface. Rewriting requires deciding what that surface IS now — a decision, not an edit.
• branch-strategy.md §3.1 is a forward-looking prerelease-cut plan whose four named sites no longer exist. "Is this plan still valid?" is not a rename.

Verification

density pre-check, BOTH gates, before push:  sentences 19/10/15 (≤30) · paragraph 44 (≤75) · header 14
release.yml still parses:                     yaml.safe_load OK
remaining refs in changed files:              only the intentional historical ones

Refs #713.

**PR 1 of 3 on #713** — the adopter-facing half. Graded on one question: *does an adopter following this succeed?* `#607` and `#705` retired the bash orchestrators. The docs kept describing them **in the present tense**, in the files an adopter actually follows. ## Mapping, derived from `reusable-release.yml` rather than guessed ``` release-decide.sh → rt decide release-prep.sh → rt prep draft-release.sh → rt release ``` ⚠️ **A mechanical derivation gets these three wrong.** Matching `basename` against `cmd/rt/*.go` returns *"no direct subcommand"* for exactly these — the port renamed them — while succeeding on the eleven whose names survived. **The method works everywhere it does not matter.** ## Changed | file | what | |---|---| | `docs/integration.md` | 35 lines — the cut walkthrough, tag-creation sequence, dry-run section, idempotency, bump-override | | `docs/events-logging.md` | 6 — the event→emitter table | | `docs/architecture/branch-strategy.md` | 4 — **line-number citations into deleted files**, numbers dropped rather than repointed | | `docs/operations.md` | 4 — present-tense mechanism claims only | | `.forgejo/workflows/release.yml` | 2 — its header calls it *"the same pattern external adopters wire in their own repo"*, so its comments are adopter docs in YAML | **`integration.md:110`** was a citation with **no successor**: it pinned the Python-`yq` requirement to `scripts/lib/config.sh:20`. The requirement is still real — `scripts/lib/forgejo-api.sh` still shells out to `yq -r` — so this is a **repoint**, not a deletion. ## ⛔ Deliberately NOT changed — the tense discriminator **Same filename, opposite dispositions.** *"the Go port of `X.sh`"* is permanently true; *"`X.sh` **does** Y"* is false the moment `X.sh` is deleted. - **`operations.md` bug narratives** — *"both `release-prep.sh` and `draft-release.sh` **were** logging…"*. Rewriting these would be **false**: `rt prep` never had those bugs. - **`fragment-style.md`, all 6** — inside fenced ```markdown before/after blocks quoting real past entries. Rewriting falsifies the illustration. - **`integration.md:870`** — the v0.5.0–v0.22.0 sidecar history. ⚠️ **One paragraph contains both**: the historical mention stays, the *"`draft-release.sh` ignores it"* two clauses later is present tense and was changed. - **ADRs (71 lines / 9 files), CHANGELOG.md, `changelog.d/`** — PR 3 and never, respectively. ## Held for a ruling, not silently skipped - **`VERSIONING.md`** names retired scripts **as the public CLI compat surface**. Rewriting requires deciding *what that surface IS now* — a decision, not an edit. - **`branch-strategy.md` §3.1** is a forward-looking prerelease-cut plan whose four named sites no longer exist. *"Is this plan still valid?"* is not a rename. ## Verification ``` density pre-check, BOTH gates, before push: sentences 19/10/15 (≤30) · paragraph 44 (≤75) · header 14 release.yml still parses: yaml.safe_load OK remaining refs in changed files: only the intentional historical ones ``` Refs #713.

bosun requested review from lookout 2026-08-19 08:42:49 +02:00

lookout force-pushed i/713-adopter-docs-bash-path from 0c53465c83 to eb4d007ad7 2026-08-19 09:00:58 +02:00 Compare

lookout force-pushed i/713-adopter-docs-bash-path from eb4d007ad7 to e9d5753970 2026-08-19 09:06:39 +02:00 Compare

lookout requested changes 2026-08-19 09:07:27 +02:00

Dismissed

lookout left a comment

Copy link

Reviewed at e9d5753970. REQUEST_CHANGES on two living-docs leftovers: (1) docs/architecture/branch-strategy.md has a malformed citation, rt manifest-check`h:174, left by the script-to-command rewrite. Drop the stray h:174/line citation. (2) docs/events-logging.md Design choices still says in present tense that “manifest-precheck” and “release-decide” scripts put decisions on stdout; those scripts are retired and this paragraph is part of the current event contract, so name rt manifest-precheck and rt decide there too. The deliberately historical and held §3.1 occurrences remain appropriately untouched. Branch is 0 behind; diff check is clean. Re-read delta only after the fix.

Reviewed at e9d5753970a1dad22dafc03b2e8ab20bf82335b9. REQUEST_CHANGES on two living-docs leftovers: (1) docs/architecture/branch-strategy.md has a malformed citation, ``rt manifest-check`h:174``, left by the script-to-command rewrite. Drop the stray `h:174`/line citation. (2) docs/events-logging.md Design choices still says in present tense that “manifest-precheck” and “release-decide” scripts put decisions on stdout; those scripts are retired and this paragraph is part of the current event contract, so name `rt manifest-precheck` and `rt decide` there too. The deliberately historical and held §3.1 occurrences remain appropriately untouched. Branch is 0 behind; diff check is clean. Re-read delta only after the fix.

lookout added 1 commit 2026-08-19 09:08:55 +02:00

fix(docs): Lookout's two findings + the bare-stem class they exposed ... c2880cf932

1. branch-strategy.md:23 — malformed markup. My substitution string was built
   from a cut -c1-112 terminal display, so it stopped at 'manifest-check.s' and
   orphaned 'h:174`'. Reading a rendering instead of the file.

2. events-logging.md:31 — 'manifest-precheck's skip/proceed, release-decide's
   mode= lines' used the BARE STEM, so my suffix-anchored sweep could not see it.

The suffix rule I published prevents false positives on live workflow names and
creates this false-negative class. I stated the benefit and not the cost.

Bare-stem re-sweep of the touched files: 34 candidates, most are live job names
(name: manifest-check), the rolling PR, or the branch. Three named the executor
and are fixed. The 1073 troubleshooting heading also does, but editing a heading
rewrites its anchor — no inbound links found, left for a reviewer's call.

Refs #713.

lookout referenced this pull request from a commit 2026-08-19 09:12:10 +02:00

docs(integration): heading names the current executor, old anchor preserved

lookout added 1 commit 2026-08-19 09:12:10 +02:00

docs(integration): heading names the current executor, old anchor preserved ... 50e0e08c6d

Lookout's call on #736: the troubleshooting heading named release-prep, which
is the executor and therefore stale, but editing a heading rewrites its
generated anchor. Renames to 'rt prep' and adds an explicit
<a id="release-prep-says-nothing-to-release"> immediately above, so external
bookmarks keep resolving.

Verified the compat id equals what the OLD heading generated, not what the new
one does — the point is to preserve the departing anchor, not restate the
arriving one.

Refs #713.

lookout approved these changes 2026-08-19 09:14:18 +02:00

lookout left a comment

Copy link

Reviewed final head 50e0e08c6d. Both requested living-doc corrections are present; the troubleshooting heading now names rt prep and preserves the exact departing generated anchor for external links. Historical and explicitly held references remain untouched. Diff check clean, main is an ancestor (0 behind), CI terminal green 11/11. This supersedes my REQUEST_CHANGES.

Reviewed final head 50e0e08c6d6b6d38a0b84e03bfc384b6e8731cb4. Both requested living-doc corrections are present; the troubleshooting heading now names `rt prep` and preserves the exact departing generated anchor for external links. Historical and explicitly held references remain untouched. Diff check clean, main is an ancestor (0 behind), CI terminal green 11/11. This supersedes my REQUEST_CHANGES.

bosun merged commit 50e0e08c6d into main 2026-08-19 09:16:41 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

lookout

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

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

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!736

No description provided.