feat(prep): a release without fragments gets its notes from feat/fix commit subjects (#1529) #1531

Merged

alex merged 18 commits from claude/1529-commit-notes into main 2026-10-04 00:12:31 +02:00

Conversation 12 Commits 18 Files changed 45 +4834 -504

claude commented 2026-10-03 03:21:14 +02:00

Member

• Copy link
• Copy Markdown

Refs #1529

In short

• A release without fragments now gets its changelog from its commit subjects:
  • feat lines go under Added;
  • fix lines go under Fixed;
  • breaking changes, of any type, go under Upgrade.
• A release with fragments, or with text written by hand under ## [Unreleased], works exactly as today. Its output is byte-identical to main.
• There is no config key. Adopters need only the pin bump to the next toolkit tag.
• Keeping things out:
  • one commit: a Release-Notes: skip trailer;
  • a whole release: an empty fragment, which renders None.. Two caveats: its kind still asks for its bump (an empty *.fixed.md can trigger a patch release on its own), and rt fragment-check v0.48.2 or later refuses empty fragments, so repos running that check use the trailer.
• ADR-0012 is Accepted (operator ratification 2026-10-03, commit 47091ff). ADR-0011 is marked as superseded in part. The measurements, mechanics and edge cases are in its companion, docs/adr/0012-commit-subject-release-notes-details.md, next to the ADR.

This replaces the first design on this branch, an opt-in "mixed mode". The operator's review redirected it (comments 114541 and 114651). The first seven commits stay in the history; the newer ones carry the new design.

Two behaviours the operator accepted with ADR-0012

1. A version that was prepared but never tagged.
   • The situation: the CHANGELOG has a section for a version, but no tag exists for it. That happens when a release PR was merged and the cut was then declined.
   • What rt now does: it starts the commit window at that version's prepare commit, so the rolling PR keeps refreshing. It does this only when the checkout has all its tags and no tag contains that commit.
   • Otherwise it refuses, naming the likely cause (a shallow clone, or tags not fetched).
2. The first release of a repository (no version section in the CHANGELOG yet).
   • What rt does: it walks the whole history, as release-please does without its bootstrap-sha setting.
   • If the repository already has tags matching tag_format, rt prints a warning naming the newest one, instead of refusing.

How it was checked (at b20b59e)

• Lint: golangci-lint 2.12.1 in CI's own image (forgejo-ci-go:latest) reports 0 issues.
• Suites: all 30 packages pass in that image and natively on Windows. gofmt is clean, and go vet passes after every commit.
• Mutation testing: every new guard is killed by a deliberately broken variant. The details doc lists them.
• Storey with its 5 fragments (the pending v0.2.0): output byte-identical to rt from main.
• Storey after a simulated v0.2.0:
  • A fix: commit alone: ### Fixed gets "game: the bench quits after its last bar (#59)".
  • Plus an empty changelog.d/59.fixed.md: all six sections "None.".
  • A release_notes: key in the config: refused as an unknown key, exactly as main refuses it.
  • rt decide: a lone chore: gives no release; adding an empty 59.fixed.md gives v0.2.1; an empty 59.added.md gives v0.3.0.
• Toolkit-self: the window starts at v0.64.0 (19 commits), not v0.62.4 (88 commits). git describe cannot see the toolkit's own tags, because since v0.63.0 they sit on a commit off main.

Details

Decision tree. ADR-0012 has it; the companion document has the measurements.

• Where the notes come from: fragments or [Unreleased] text when the release has any; otherwise commit subjects.
  • Mixed mode was dropped. It re-created the #717 leak on a replay of v0.38.0, and turned one change (#1526) into five bullets.
  • A "fragments only" switch was dropped. No measured release would have used it: all 31 toolkit prepares and purser's 4 had fragments or [Unreleased] text, and ember, cellblock and tmux-tell's 6 fragment-less releases already published their subjects. A key can be added later without breaking anyone.
• Which types render: feat and fix, plus breaking changes under Upgrade (the BREAKING CHANGE: footer if present, else the subject). perf/revert wait: they would need rt decide to change too.
• Declining a note:
  • a Release-Notes: skip trailer on the commit itself, which survives rebases;
  • Release-Notes: skip <sha> in a later commit, safe only for commits already on main;
  • an empty fragment for a whole release;
  • typing housekeeping as chore/ci/docs/test.

Commits since the first review (newest first)

Commit	What
e5fcf1d docs(adr)	The companion moves next to the ADR as docs/adr/0012-commit-subject-release-notes-details.md; links rewritten
47091ff docs(adr)	Ratification: ADR-0012 accepted, ADR-0011 superseded in part, arc42/09 updated
b20b59e chore(changelog)	The #1529 fragment advises the empty fragment instead of the dropped key
4b910d1 docs	ADR-0012, its companion and the docs: the key is gone; the empty fragment, its bump and the fragment-check caveat are described
72f09c5 feat(prep)	The release_notes key removed. Recovery refuses when the config does not load, and gives its own remedy for an unanchored window
98ed9c4 docs(adr)	ADR-0012 cut down to its decision; the details move to a companion document
fb7b9e9 fix(lint)	Two staticcheck findings (ST1008, QF1001)
db869fa chore(changelog)	The fragment becomes a changed entry
d7502b2 docs	The docs describe the per-release default
2197f3f feat(prep)	The per-release rule, breaking changes under Upgrade, the window anchor, recovery's mode detection, scope escaping
4d78c75 docs(adr)	ADR-0012 back to Proposed and rewritten
6979efc…8ddb0f8	The first design (opt-in mixed mode), kept as history

No re-pin is needed: toolkit-self floats @main (AGENTS.md §2.1). Adopters get this from the next cut tag. There is no new verb or flag, no workflow file change, and the code is ASCII-only.

Follow-ups filed from this review:

• #1532: a stable rt prep refuses tags that are not vX.Y.Z.
• #1533: rt decide assumes v-prefixed tags.
• #1534: pinning the reusables to a toolkit branch.
• #1535: the Gitea copy of the release workflow checks the wrong directory.
• #1536: outdated release-please notes in ADR-0005.
• #1537: the recovery workflow's git add lacks its guard.
• #1538: rt prep --dry-run inside a git worktree stages its preview into that worktree.

Small leftovers outside this PR:

• docs/architecture/c4/release-toolkit.likec4:123 still says note rendering is opt-in. Editing it triggers the C4 deploy.
• The recovery workflow's PR text says "fragments were restored" even when none were.
• Two dead links from before this PR: integration.md → conventions.md#pre-10-opt-in-…, and ADR-0006 → AGENTS.md#10-….

Ratification (47091ff, docs only):

• ADR-0012 is accepted, and its until-accepted wording is gone.
• ADR-0011's status reads "superseded in part by ADR-0012" for a release with no fragment and no [Unreleased] text.
• arc42/09's 0011, 0012 and 0006 rows and §9.1 are updated.

After it: the doc tests and the full suite pass, and the anchor check finds 0 unresolved links. ADR-0005's outdated release-please notes stay with #1536.

Verify at source

An agent can do steps 1 and 2 and post the result as a comment. Approving stays with you: the forge does not let claude approve its own PR. Pin the approval to this head with rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head e5fcf1dd8c5afc80ea1f7601a64f34044750da1d.

1. Build rt from e5fcf1d. Run rt prep --dry-run on a Storey clone (expected: only the 5 fragments). Then, on the same clone after a local v0.2.0 tag, add a fix: commit (expected: a Fixed line), and then an empty fragment (expected: all "None.").
2. Break one guard, for example remove "fix": true from noteTypes in internal/prep/commit_notes.go, and see a test turn red.

🤖 Generated with Claude Code

Refs #1529 ## In short - **A release without fragments now gets its changelog from its commit subjects:** - `feat` lines go under **Added**; - `fix` lines go under **Fixed**; - breaking changes, of any type, go under **Upgrade**. - **A release with fragments, or with text written by hand under `## [Unreleased]`, works exactly as today.** Its output is byte-identical to `main`. - **There is no config key.** Adopters need only the pin bump to the next toolkit tag. - **Keeping things out:** - one commit: a `Release-Notes: skip` trailer; - a whole release: an empty fragment, which renders `None.`. Two caveats: its kind still asks for its bump (an empty `*.fixed.md` can trigger a patch release on its own), and `rt fragment-check` v0.48.2 or later refuses empty fragments, so repos running that check use the trailer. - **ADR-0012 is *Accepted*** (operator ratification 2026-10-03, commit `47091ff`). ADR-0011 is marked as superseded in part. The measurements, mechanics and edge cases are in its companion, [`docs/adr/0012-commit-subject-release-notes-details.md`](https://git.frankenbit.de/frankenbit/release-toolkit/src/commit/e5fcf1dd8c5afc80ea1f7601a64f34044750da1d/docs/adr/0012-commit-subject-release-notes-details.md), next to the ADR. This replaces the first design on this branch, an opt-in "mixed mode". The operator's review redirected it (comments 114541 and 114651). The first seven commits stay in the history; the newer ones carry the new design. ## Two behaviours the operator accepted with ADR-0012 1. **A version that was prepared but never tagged.** - **The situation:** the CHANGELOG has a section for a version, but no tag exists for it. That happens when a release PR was merged and the cut was then declined. - **What rt now does:** it starts the commit window at that version's prepare commit, so the rolling PR keeps refreshing. It does this only when the checkout has all its tags and no tag contains that commit. - **Otherwise it refuses**, naming the likely cause (a shallow clone, or tags not fetched). 2. **The first release of a repository** (no version section in the CHANGELOG yet). - **What rt does:** it walks the whole history, as release-please does without its `bootstrap-sha` setting. - **If the repository already has tags matching `tag_format`,** rt prints a warning naming the newest one, instead of refusing. ## How it was checked (at `b20b59e`) - **Lint:** `golangci-lint` 2.12.1 in CI's own image (`forgejo-ci-go:latest`) reports 0 issues. - **Suites:** all 30 packages pass in that image and natively on Windows. gofmt is clean, and `go vet` passes after every commit. - **Mutation testing:** every new guard is killed by a deliberately broken variant. The details doc lists them. - **Storey with its 5 fragments (the pending v0.2.0):** output byte-identical to `rt` from `main`. - **Storey after a simulated v0.2.0:** - **A `fix:` commit alone:** `### Fixed` gets "**game**: the bench quits after its last bar (#59)". - **Plus an empty `changelog.d/59.fixed.md`:** all six sections "None.". - **A `release_notes:` key in the config:** refused as an unknown key, exactly as `main` refuses it. - **`rt decide`:** a lone `chore:` gives no release; adding an empty `59.fixed.md` gives v0.2.1; an empty `59.added.md` gives v0.3.0. - **Toolkit-self:** the window starts at v0.64.0 (19 commits), not v0.62.4 (88 commits). `git describe` cannot see the toolkit's own tags, because since v0.63.0 they sit on a commit off `main`. ## Details **Decision tree.** ADR-0012 has it; the companion document has the measurements. - **Where the notes come from:** fragments or `[Unreleased]` text when the release has any; otherwise commit subjects. - **Mixed mode** was dropped. It re-created the #717 leak on a replay of v0.38.0, and turned one change (#1526) into five bullets. - **A "fragments only" switch** was dropped. No measured release would have used it: all 31 toolkit prepares and purser's 4 had fragments or `[Unreleased]` text, and ember, cellblock and tmux-tell's 6 fragment-less releases already published their subjects. A key can be added later without breaking anyone. - **Which types render:** `feat` and `fix`, plus breaking changes under Upgrade (the `BREAKING CHANGE:` footer if present, else the subject). `perf`/`revert` wait: they would need `rt decide` to change too. - **Declining a note:** - a `Release-Notes: skip` trailer on the commit itself, which survives rebases; - `Release-Notes: skip <sha>` in a later commit, safe only for commits already on `main`; - an empty fragment for a whole release; - typing housekeeping as `chore`/`ci`/`docs`/`test`. **Commits since the first review (newest first)** | Commit | What | |---|---| | `e5fcf1d` docs(adr) | The companion moves next to the ADR as `docs/adr/0012-commit-subject-release-notes-details.md`; links rewritten | | `47091ff` docs(adr) | Ratification: ADR-0012 accepted, ADR-0011 superseded in part, arc42/09 updated | | `b20b59e` chore(changelog) | The #1529 fragment advises the empty fragment instead of the dropped key | | `4b910d1` docs | ADR-0012, its companion and the docs: the key is gone; the empty fragment, its bump and the fragment-check caveat are described | | `72f09c5` feat(prep) | The `release_notes` key removed. Recovery refuses when the config does not load, and gives its own remedy for an unanchored window | | `98ed9c4` docs(adr) | ADR-0012 cut down to its decision; the details move to a companion document | | `fb7b9e9` fix(lint) | Two staticcheck findings (ST1008, QF1001) | | `db869fa` chore(changelog) | The fragment becomes a `changed` entry | | `d7502b2` docs | The docs describe the per-release default | | `2197f3f` feat(prep) | The per-release rule, breaking changes under Upgrade, the window anchor, recovery's mode detection, scope escaping | | `4d78c75` docs(adr) | ADR-0012 back to Proposed and rewritten | | `6979efc`…`8ddb0f8` | The first design (opt-in mixed mode), kept as history | **No re-pin is needed:** toolkit-self floats `@main` (AGENTS.md §2.1). Adopters get this from the next cut tag. There is no new verb or flag, no workflow file change, and the code is ASCII-only. **Follow-ups filed from this review:** - #1532: a stable `rt prep` refuses tags that are not `vX.Y.Z`. - #1533: `rt decide` assumes `v`-prefixed tags. - #1534: pinning the reusables to a toolkit branch. - #1535: the Gitea copy of the release workflow checks the wrong directory. - #1536: outdated release-please notes in ADR-0005. - #1537: the recovery workflow's `git add` lacks its guard. - #1538: `rt prep --dry-run` inside a git worktree stages its preview into that worktree. Small leftovers outside this PR: - `docs/architecture/c4/release-toolkit.likec4:123` still says note rendering is opt-in. Editing it triggers the C4 deploy. - The recovery workflow's PR text says "fragments were restored" even when none were. - Two dead links from before this PR: `integration.md` → `conventions.md#pre-10-opt-in-…`, and ADR-0006 → `AGENTS.md#10-…`. **Ratification** (`47091ff`, docs only): - ADR-0012 is accepted, and its until-accepted wording is gone. - ADR-0011's status reads "superseded in part by ADR-0012" for a release with no fragment and no `[Unreleased]` text. - arc42/09's 0011, 0012 and 0006 rows and §9.1 are updated. After it: the doc tests and the full suite pass, and the anchor check finds 0 unresolved links. ADR-0005's outdated release-please notes stay with #1536. ## Verify at source An agent can do steps 1 and 2 and post the result as a comment. Approving stays with you: the forge does not let `claude` approve its own PR. Pin the approval to this head with `rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head e5fcf1dd8c5afc80ea1f7601a64f34044750da1d`. 1. Build `rt` from `e5fcf1d`. Run `rt prep --dry-run` on a Storey clone (expected: only the 5 fragments). Then, on the same clone after a local v0.2.0 tag, add a `fix:` commit (expected: a Fixed line), and then an empty fragment (expected: all "None."). 2. Break one guard, for example remove `"fix": true` from `noteTypes` in `internal/prep/commit_notes.go`, and see a test turn red. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude added the

priority

medium

size

L

kind

feature

labels 2026-10-03 03:21:14 +02:00

claude added 7 commits 2026-10-03 03:21:14 +02:00

feat(config): read release_notes.source and refuse a block without a known source (#1529) ... 8ddb0f8b65

release-toolkit.yml gains an optional release_notes block. source is
fragments (the ADR-0011 default, also what an absent block means) or
commits. A block that is present but empty, null or carries an unknown
source is a schema violation, so an adopter who writes the block always
chose something. config.schema.json carries the same shape.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(changelog): join the bullets of every note source under a heading as one list (#1529) ... b1eb86f018

When fragment bullets and another source's bullets meet under one
heading, MergeSections now emits one list instead of two runs split by
blank lines. The default compose renders no commit notes, so its output
is unchanged; the four ADR-0011 tests and the goldens stay green.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(prep): render feat and fix subjects as notes under release_notes.source: commits (#1529) ... 72dea53970

Opted in, rt prep walks the window since the last tag and renders feat
subjects under Added and fix subjects under Fixed, through
RenderCommitSections and register.ScrubLine. perf and refactor stay
bump-only. A subject renders no note when its commit added a visible
fragment, names a fragment id, declines with a Release-Notes: skip
trailer, is named by a later Release-Notes: skip <sha>, or is the
toolkit's own fold-back commit; a numeric fragment replaces the bullets
that cite its number. The walk refuses when it cannot anchor (no
matching tag although the CHANGELOG has a cut), and the last-tag match
follows tag_format. Without the key nothing walks and the output is
byte-identical.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(recover): subtract a stranded prepare's commit notes and accept a commit-only prepare (#1529) ... ba8df5d655

Opted in, rt recover-pending-cut subtracts the commit notes the
stranded prepare rendered, so a re-prepare cannot render them twice. It
accepts a prepare that consumed no fragment only when the prepare
deleted none and changelog.d at its parent holds no visible fragment
(absent, or a real tree rather than a symlink). A config that fails to
load while it names release_notes is refused instead of read as the
fragment-only default. The default path is unchanged.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

fix(gates): the fragment-density scope note names the commit-note opt-in (#1529) ... c14019f2de

The PASS line said commits add no note bullets, which stops being true
for an adopter on release_notes.source: commits. It now says so only
for the default.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(adr): ADR-0012 records the opt-in commit-subject release notes (#1529) ... d474ea487f

ADR-0012 supersedes ADR-0011 item 3 in part, for adopters who opt in,
as a decision tree: the key, why feat and fix only, the decline grammar,
fragment wins, the walk anchor, recovery, the ADR-0005 wheel check and
the ADR-0006 boundary. ADR-0011, ADR-0006, architecture.md, the arc42
chapters and the C6 contract now say bump-only by default.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(integration): set up and run release_notes.source: commits (#1529) ... 6979efcdd4

integration.md gains the key, the rule that the key never lands before
a pin that knows it (an older rt refuses it in prep, manifest-check and
prepared-uncut-check, while rt decide silently falls back), an FAQ and
how the cut grades commit bullets. conventions.md, fragment-style.md,
fragment-coverage-gate.md, operations.md and the README follow.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude requested review from alex 2026-10-03 03:21:18 +02:00

claude commented 2026-10-03 12:14:57 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD. Please don't review or approve the current head 6979efc. The design changes before review, after the operator's questions on 2026-10-03.

What changes, as new commits on this branch (no amend, no force-push):

1. ADR-0012 goes back to Proposed. It becomes accepted only once the operator agrees to the rewritten text.
2. Commit notes become the default, decided per release:
   • if a release has fragments or hand-written [Unreleased] text, only those are used;
   • otherwise its feat/fix subjects become the notes;
   • release_notes.source: fragments stays as the way back to today's behaviour.
3. Mixed mode (fragments and commit notes in one release) is dropped.
4. The commit window is anchored at the tag of the CHANGELOG's newest version. git describe cannot see the toolkit's own release tags: since v0.63.0 they sit on a "pin action image" commit off main, so describe answers v0.62.4. A range from that tag is still correct: v0.64.0..main gives 19 commits, against 88 from v0.62.4.
5. Breaking commits render under ### Upgrade.

I'll post the new full head SHA here when it is pushed, and lift the HOLD then.

**HOLD.** Please don't review or approve the current head `6979efc`. The design changes before review, after the operator's questions on 2026-10-03. What changes, as new commits on this branch (no amend, no force-push): 1. **ADR-0012 goes back to `Proposed`.** It becomes accepted only once the operator agrees to the rewritten text. 2. **Commit notes become the default, decided per release:** - if a release has fragments or hand-written `[Unreleased]` text, only those are used; - otherwise its `feat`/`fix` subjects become the notes; - `release_notes.source: fragments` stays as the way back to today's behaviour. 3. **Mixed mode (fragments and commit notes in one release) is dropped.** 4. **The commit window is anchored at the tag of the CHANGELOG's newest version.** `git describe` cannot see the toolkit's own release tags: since v0.63.0 they sit on a "pin action image" commit off `main`, so describe answers v0.62.4. A range from that tag is still correct: `v0.64.0..main` gives 19 commits, against 88 from v0.62.4. 5. **Breaking commits render under `### Upgrade`.** I'll post the new full head SHA here when it is pushed, and lift the HOLD then.

claude added 4 commits 2026-10-03 14:49:20 +02:00

docs(adr): ADR-0012 is proposed again, rewritten for one note source per release (#1529) ... 4d78c75ba4

The operator asked for the ADR to start as proposed and to become
accepted only after agreement (arc42 OC-1, the ADR-0009 precedent), and
redirected the design (PR 1531 comment 114541): a release with no
fragment and no [Unreleased] text renders its feat/fix subjects by
default, release_notes.source: fragments keeps today's behaviour, and
mixed mode is dropped. ADR-0012 is rewritten for that as a decision tree
and renamed to match. ADR-0011 returns to main's text until ADR-0012 is
ratified; arc42/09 lists ADR-0012 as proposed.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

feat(prep): a release with no fragment and no [Unreleased] text renders its feat/fix subjects (#1529) ... 2197f3f1f2

The note source is decided per release. Fragments or authored
[Unreleased] text keep the release on exactly today's output; otherwise
feat subjects render under Added and fix under Fixed, and a breaking
commit of any type renders once under Upgrade (its BREAKING CHANGE
footer, else its description). release_notes.source is auto (the
default) or fragments; the commits value and mixed mode are gone, and
with them the fragment-interplay exclusions and the one-list merge.

The window starts at the tag of the CHANGELOG's newest cut. git describe
cannot see the toolkit's own tags, which sit off main since v0.63.0, so
it answered v0.62.4; v0.64.0..main is the right range. A cut whose tag
is missing refuses, unless the checkout has its tags and no tag holds
that version's prepare commit (a declined cut), where the window starts
at the prepare. Recovery tells a stranded prepare's mode from what it
consumed. Scopes are escaped so ** and _ cannot break the bullet.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: describe the per-release note source, its anchor and recovery (#1529) ... d7502b29a5

README, conventions, integration, the fragment-coverage gate, fragment
style, operations, architecture.md, the C6 contract, arc42 and ADR-0006
now say: a release without fragments or [Unreleased] text gets its
feat/fix subjects as notes, breaking changes under Upgrade, and
release_notes.source: fragments restores the old behaviour. Storey-like
adopters need only the pin bump.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

chore(changelog): the #1529 fragment becomes a changed entry with its upgrade advice (#1529) ... db869fada7

Fragment-less releases now get notes by default, a change in behaviour,
so the entry is changed rather than added and tells adopters who want
the old "None." sections to set release_notes.source: fragments.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude referenced this pull request 2026-10-03 14:51:03 +02:00

bug(prep): a stable rt prep refuses every tag that is not vX.Y.Z, so an adopter with any other tag_format cannot cut #1532

claude referenced this pull request 2026-10-03 14:51:41 +02:00

bug(decide): rt decide reads tags and prepare commits as v-prefixed, so a release-{version} adopter's merged prepare is never detected as a cut #1533

claude referenced this pull request 2026-10-03 14:52:09 +02:00

feat(bootstrap): let a consumer pin the reusables to a toolkit branch, to try unreleased changes before a cut #1534

claude referenced this pull request 2026-10-03 14:52:37 +02:00

bug(release): the Gitea twin's secrets-inherit-check reads .forgejo/workflows and matches only .forgejo spellings, so a Gitea adopter is never graded #1535

claude referenced this pull request 2026-10-03 14:53:01 +02:00

docs(adr): ADR-0005's release-please evidence is out of date — the action and CLI take an API URL, and the provider tracker has moved #1536

claude referenced this pull request 2026-10-03 14:53:20 +02:00

chore(recovery): guard the recover workflow's git add --all -- changelog.d (AGENTS.md section 5a) instead of relying on the verb to create the directory #1537

claude referenced this pull request 2026-10-03 14:53:46 +02:00

bug(prep): rt prep --dry-run inside a linked worktree stages the whole preview into that worktree's index — the scratch copy shares its .git #1538

claude referenced this pull request 2026-10-03 14:54:12 +02:00

bug(prep): a stable rt prep refuses every tag that is not vX.Y.Z, so an adopter with any other tag_format cannot cut #1532

claude referenced this pull request 2026-10-03 14:54:13 +02:00

bug(decide): rt decide reads tags and prepare commits as v-prefixed, so a release-{version} adopter's merged prepare is never detected as a cut #1533

claude changed title from feat(prep): opt-in release notes from feat/fix commit subjects — release_notes.source: commits (#1529) to feat(prep): a release without fragments gets its notes from feat/fix commit subjects (#1529) 2026-10-03 14:55:11 +02:00

claude commented 2026-10-03 14:55:20 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD lifted. New head: db869fada7357d1296bacd640133e6663c55211c. It adds four new commits on top of 6979efc, with no amend and no force-push. The description is rewritten: a short summary first, the details below.

Before approving, please pin the review to this exact head with rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head db869fada7357d1296bacd640133e6663c55211c.

Two design calls are waiting for your decision. Both are described under "Two decisions for you" in the description:

1. A version that was prepared but never tagged: rt starts the window at its prepare commit, instead of refusing.
2. A first release over a history that already has matching tags: rt warns, instead of refusing.

ADR-0012 stays Proposed until you agree. The ratification edits are listed at the end of the description.

**HOLD lifted.** New head: `db869fada7357d1296bacd640133e6663c55211c`. It adds four new commits on top of `6979efc`, with no amend and no force-push. The description is rewritten: a short summary first, the details below. Before approving, please pin the review to this exact head with `rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head db869fada7357d1296bacd640133e6663c55211c`. Two design calls are waiting for your decision. Both are described under "Two decisions for you" in the description: 1. A version that was prepared but never tagged: rt starts the window at its prepare commit, instead of refusing. 2. A first release over a history that already has matching tags: rt warns, instead of refusing. ADR-0012 stays *Proposed* until you agree. The ratification edits are listed at the end of the description.

claude commented 2026-10-03 15:21:56 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD. Two more commits are coming on top of db869fa, so please don't approve that head.

1. A lint fix. CI's golangci-lint found two staticcheck issues:

   • ST1008: a test helper returned its error first;
   • QF1001: a negated condition, which De Morgan's law simplifies.

   Both are fixed and checked with CI's own image (forgejo-ci-go:latest, golangci-lint 2.12.1): 0 issues, and all 30 packages pass there and natively on Windows.

2. ADR-0012 shortened, as the operator asked. At 558 lines it buries the decision. The ADR keeps the decision, the decision tree and the consequences. The measurements and mechanics move to a companion document that it links to. ADR-0012 stays Proposed until the operator has read the short version.

I'll post the new full head SHA here once both are pushed.

**HOLD.** Two more commits are coming on top of `db869fa`, so please don't approve that head. 1. **A lint fix.** CI's `golangci-lint` found two staticcheck issues: - ST1008: a test helper returned its error first; - QF1001: a negated condition, which De Morgan's law simplifies. Both are fixed and checked with CI's own image (`forgejo-ci-go:latest`, golangci-lint 2.12.1): 0 issues, and all 30 packages pass there and natively on Windows. 2. **ADR-0012 shortened, as the operator asked.** At 558 lines it buries the decision. The ADR keeps the decision, the decision tree and the consequences. The measurements and mechanics move to a companion document that it links to. ADR-0012 stays *Proposed* until the operator has read the short version. I'll post the new full head SHA here once both are pushed.

claude added 2 commits 2026-10-03 16:02:34 +02:00

fix(lint): return the recovery helper's error last and apply De Morgan to the scope escape (#1529) ... fb7b9e9968

CI's golangci-lint (staticcheck) flagged ST1008 on recoverAndRead, which
returned its error first, and QF1001 on markdownScope's underscore case.
The helper now returns (stdout, stderr, changelog, error), and the
underscore condition negates each operand instead of the whole
conjunction; the short-circuit order still guards both index reads.
golangci-lint 2.12.1 in the CI image (forgejo-ci-go:latest) reports 0
issues, and the suite passes there and natively on Windows.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs(adr): keep ADR-0012 to its decision and move the details to a companion document (#1529) ... 98ed9c466f

At 558 lines ADR-0012 buried its decision, and the operator asked for
the essence to stay in the ADR and the details to move out. The ADR now
holds the context, the rules in plain words, the decision tree, the
consequences, its relationship to ADR-0011, 0005, 0006 and 0002, and
the ratification list (247 lines). Measurements, mechanics, edge cases,
the trailer-block rules, the anchor algorithm, recovery details and the
replays move, unshortened, to
docs/architecture/commit-subject-release-notes.md, a companion like
test-strategy.md. No content is lost; the status stays proposed.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude commented 2026-10-03 16:03:38 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD lifted. New head: 98ed9c466fc3ddd6e544228d8de84bda78b3e875.

• fb7b9e9 fixes the two staticcheck findings. golangci-lint 2.12.1 in CI's image reports 0 issues.
• 98ed9c4 shortens ADR-0012 to 247 lines. The details moved, unshortened, to docs/architecture/commit-subject-release-notes.md.

Please read the short ADR: ADR-0012 at this head.

Once the operator agrees, including the two decisions listed in the description, one more commit sets it to Accepted. That commit carries the edits listed under "Ratification edits". The approval then goes on that final head, checked with rt review-submit-check.

**HOLD lifted.** New head: `98ed9c466fc3ddd6e544228d8de84bda78b3e875`. - `fb7b9e9` fixes the two staticcheck findings. golangci-lint 2.12.1 in CI's image reports 0 issues. - `98ed9c4` shortens ADR-0012 to 247 lines. The details moved, unshortened, to `docs/architecture/commit-subject-release-notes.md`. Please read the short ADR: [ADR-0012 at this head](https://git.frankenbit.de/frankenbit/release-toolkit/src/commit/98ed9c466fc3ddd6e544228d8de84bda78b3e875/docs/adr/0012-commit-subject-release-notes.md). Once the operator agrees, including the two decisions listed in the description, one more commit sets it to *Accepted*. That commit carries the edits listed under "Ratification edits". The approval then goes on that final head, checked with `rt review-submit-check`.

claude commented 2026-10-03 21:07:45 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD. One more design change is coming on top of 98ed9c4, decided with the operator:

1. release_notes.source: fragments is dropped, and with it the whole release_notes key.

   • No measured release would have used it: all 31 toolkit cuts and purser's 4 had fragments.
   • Without the key, no adopter needs a config change, and there is no pin-before-key hazard.
   • A key can be added again later without breaking anyone, if a real need shows up.

2. "Nothing to announce" for a whole release becomes an empty fragment. Any fragment switches its release to fragments-only, and an empty one adds nothing. Measured with this head on a Storey copy after v0.2.0:

   • a fix: commit alone renders under ### Fixed;
   • the same commit plus an empty changelog.d/59.fixed.md renders all "None.".

   Caveat: rt fragment-check rejects an empty fragment (no summary line). Repos that run it decline per commit with Release-Notes: skip instead. This goes into the docs and gets pinned by tests.

ADR-0012 stays Proposed and gets updated to match. I'll post the new full head SHA when it is pushed.

**HOLD.** One more design change is coming on top of `98ed9c4`, decided with the operator: 1. **`release_notes.source: fragments` is dropped, and with it the whole `release_notes` key.** - No measured release would have used it: all 31 toolkit cuts and purser's 4 had fragments. - Without the key, no adopter needs a config change, and there is no pin-before-key hazard. - A key can be added again later without breaking anyone, if a real need shows up. 2. **"Nothing to announce" for a whole release becomes an empty fragment.** Any fragment switches its release to fragments-only, and an empty one adds nothing. Measured with this head on a Storey copy after v0.2.0: - a `fix:` commit alone renders under `### Fixed`; - the same commit plus an empty `changelog.d/59.fixed.md` renders all "None.". Caveat: `rt fragment-check` rejects an empty fragment (no summary line). Repos that run it decline per commit with `Release-Notes: skip` instead. This goes into the docs and gets pinned by tests. ADR-0012 stays *Proposed* and gets updated to match. I'll post the new full head SHA when it is pushed.

claude added 3 commits 2026-10-03 23:11:11 +02:00

feat(prep): drop the release_notes key; an empty fragment keeps a release's subjects out (#1529) ... 72f09c5472

The operator decided (PR 1531 comment 114651) to drop the
release_notes.source: fragments escape hatch, and with it the whole
release_notes key: no measured release would have used it, and without a
key no adopter needs a config change and no pin-before-key hazard
exists. A release_notes key is an unknown key again, as on main.

A release that should announce nothing adds an empty or whitespace-only
fragment: any fragment makes it a fragment release, and an empty one
renders nothing. Tests pin both forms. Recovery refuses to grade a
prepare that consumed no fragment when the config does not load, loads
the config once (loadDecideConfig), and gives its anchor refusal its
own remedy (NotesAnchorError.Problem) instead of prep's.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: drop the release_notes key and describe the empty fragment (#1529) ... 4b910d17eb

ADR-0012 (still proposed) and its companion record the dropped switch
and its reasons. The docs describe the empty fragment as the way a whole
release announces nothing, that it can itself request the bump of its
kind, and that rt fragment-check v0.48.2 or later refuses it, so a repo
running that check declines each commit with the trailer instead.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

chore(changelog): the #1529 fragment advises an empty fragment instead of the dropped key (#1529) ... b20b59ead0

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude commented 2026-10-03 23:12:17 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD lifted. New head: b20b59ead0d74f874f5c2501a14c03e7cdb0446d.

What changed since 98ed9c4:

• 72f09c5: the release_notes key is gone. Recovery refuses when the config does not load, and has its own remedy for a window it cannot anchor.
• 4b910d1: ADR-0012, its companion and the docs. The key is gone. The empty fragment is described with both of its caveats: its kind still asks for its bump, and rt fragment-check v0.48.2 or later refuses it.
• b20b59e: the changelog fragment's advice is updated to match.

At this head, golangci-lint in CI's image reports 0 issues. All 30 packages pass there and natively on Windows.

The ADR is still Proposed: ADR-0012 at this head. Once the operator agrees, one ratification commit follows, and the approval goes on that final head.

**HOLD lifted.** New head: `b20b59ead0d74f874f5c2501a14c03e7cdb0446d`. What changed since `98ed9c4`: - **`72f09c5`:** the `release_notes` key is gone. Recovery refuses when the config does not load, and has its own remedy for a window it cannot anchor. - **`4b910d1`:** ADR-0012, its companion and the docs. The key is gone. The empty fragment is described with both of its caveats: its kind still asks for its bump, and `rt fragment-check` v0.48.2 or later refuses it. - **`b20b59e`:** the changelog fragment's advice is updated to match. At this head, golangci-lint in CI's image reports 0 issues. All 30 packages pass there and natively on Windows. The ADR is still *Proposed*: [ADR-0012 at this head](https://git.frankenbit.de/frankenbit/release-toolkit/src/commit/b20b59ead0d74f874f5c2501a14c03e7cdb0446d/docs/adr/0012-commit-subject-release-notes.md). Once the operator agrees, one ratification commit follows, and the approval goes on that final head.

claude commented 2026-10-03 23:29:48 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD. The operator agreed to ADR-0012. The ratification commit follows on top of b20b59e: it carries the status flip and the edits under "Ratification edits". Please approve only the head I post after it.

**HOLD.** The operator agreed to ADR-0012. The ratification commit follows on top of `b20b59e`: it carries the status flip and the edits under "Ratification edits". Please approve only the head I post after it.

claude added 1 commit 2026-10-03 23:34:01 +02:00

docs(adr): ratify ADR-0012; ADR-0011 is superseded in part (#1529) ... 47091ff2c4

The operator agreed to ADR-0012 on 2026-10-03. This is its ratifying
commit (arc42 OC-1, as ADR-0009 was): its status becomes accepted and
its until-accepted wording goes, ADR-0011's status line records the
partial supersession for a release with no fragment and no [Unreleased]
text, and arc42/09's 0011, 0012 and 0006 rows and section 9.1 follow.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude commented 2026-10-03 23:34:50 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD lifted. Final head: 47091ff2c4831266b2132e7ba243379f7f973bd2.

47091ff ratifies ADR-0012:

• ADR-0012 is accepted;
• ADR-0011's status line now says "superseded in part by ADR-0012";
• arc42/09 is updated to match.

It changes docs only. After it, the doc tests and the full suite pass, and the anchor check finds 0 unresolved links.

This is the head to approve. Pin the approval to it first:

rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head 47091ff2c4831266b2132e7ba243379f7f973bd2

**HOLD lifted. Final head: `47091ff2c4831266b2132e7ba243379f7f973bd2`.** `47091ff` ratifies ADR-0012: - ADR-0012 is accepted; - ADR-0011's status line now says "superseded in part by ADR-0012"; - arc42/09 is updated to match. It changes docs only. After it, the doc tests and the full suite pass, and the anchor check finds 0 unresolved links. This is the head to approve. Pin the approval to it first: `rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head 47091ff2c4831266b2132e7ba243379f7f973bd2`

claude commented 2026-10-03 23:54:45 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD. Do not approve 47091ff yet. One docs-only commit follows, at the operator's request: ADR-0012's companion document moves next to the ADR, from docs/architecture/commit-subject-release-notes.md to docs/adr/0012-commit-subject-release-notes-details.md, and every link to it is updated.

Nothing treats that folder's files as ADRs:

• the only test that lists docs/adr/ (internal/wrappers/discover_test.go) looks for *.yml workflow files;
• adr-supersession-check reads only ADR-0001;
• nothing checks ADR numbering.

I'll post the new full head SHA when it is pushed.

**HOLD.** Do not approve `47091ff` yet. One docs-only commit follows, at the operator's request: ADR-0012's companion document moves next to the ADR, from `docs/architecture/commit-subject-release-notes.md` to `docs/adr/0012-commit-subject-release-notes-details.md`, and every link to it is updated. Nothing treats that folder's files as ADRs: - the only test that lists `docs/adr/` (`internal/wrappers/discover_test.go`) looks for `*.yml` workflow files; - `adr-supersession-check` reads only ADR-0001; - nothing checks ADR numbering. I'll post the new full head SHA when it is pushed.

claude added 1 commit 2026-10-03 23:58:42 +02:00

docs(adr): keep ADR-0012's details next to it as 0012-...-details.md (#1529) ... e5fcf1dd8c

The companion document sat apart from its ADR in docs/architecture/.
At the operator's request it moves next to it, as
docs/adr/0012-commit-subject-release-notes-details.md, so the two sort
together. Its own relative links and the ADR's 16 links to it are
rewritten; no other file linked it. Nothing treats docs/adr/ files as
ADRs by listing the folder (the one test that lists it looks for *.yml
wrappers), and no gate checks ADR numbering. A repo-wide relative-link
check gives the same result as before the move.

Refs #1529

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

claude commented 2026-10-03 23:59:28 +02:00

Author

Member

• Copy link
• Copy Markdown

HOLD lifted. Final head: e5fcf1dd8c5afc80ea1f7601a64f34044750da1d.

e5fcf1d changes docs only. The companion document now sits next to its ADR, as docs/adr/0012-commit-subject-release-notes-details.md. Git records it as a rename.

• Links: the 16 links in ADR-0012 that pointed to the companion are rewritten, and so are the companion's own relative links. No other file linked it.
• Link check: every relative link in the repo (264, in 145 files) gives the same result as before the move. The only missing targets are 2 links in docs/dead-script-namespace.md, which were already broken. The anchor check finds 0 unresolved anchors in the two files.
• Tests: internal/wrappers, internal/contracts, internal/gates and cmd/rt pass.

This is the head to approve. Pin the approval to it first:

rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head e5fcf1dd8c5afc80ea1f7601a64f34044750da1d

**HOLD lifted. Final head: `e5fcf1dd8c5afc80ea1f7601a64f34044750da1d`.** `e5fcf1d` changes docs only. The companion document now sits next to its ADR, as `docs/adr/0012-commit-subject-release-notes-details.md`. Git records it as a rename. - **Links:** the 16 links in ADR-0012 that pointed to the companion are rewritten, and so are the companion's own relative links. No other file linked it. - **Link check:** every relative link in the repo (264, in 145 files) gives the same result as before the move. The only missing targets are 2 links in `docs/dead-script-namespace.md`, which were already broken. The anchor check finds 0 unresolved anchors in the two files. - **Tests:** `internal/wrappers`, `internal/contracts`, `internal/gates` and `cmd/rt` pass. This is the head to approve. Pin the approval to it first: `rt review-submit-check --owner frankenbit --repo release-toolkit --pr 1531 --reviewed-head e5fcf1dd8c5afc80ea1f7601a64f34044750da1d`

alex approved these changes 2026-10-04 00:10:49 +02:00

alex merged commit e5fcf1dd8c into main 2026-10-04 00:12:31 +02:00

alex deleted branch claude/1529-commit-notes 2026-10-04 00:12:31 +02:00

forgejo-actions commented 2026-10-04 00:13:23 +02:00

• Copy link
• Copy Markdown

Landing identity record

• PR: #1531
• landed commit (server merge_commit_sha): e5fcf1dd8c5afc80ea1f7601a64f34044750da1d
• effective official approval(s):
  • @alex, review #7211, stamped commit: e5fcf1dd8c5afc80ea1f7601a64f34044750da1d
• replay comparison: no identity change (stamped SHA equals landed SHA)

This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

<!-- release-toolkit:landing-review-record-v1 landed=e5fcf1dd8c5afc80ea1f7601a64f34044750da1d --> ## Landing identity record - PR: #1531 - landed commit (server merge_commit_sha): `e5fcf1dd8c5afc80ea1f7601a64f34044750da1d` - effective official approval(s): - @alex, review #7211, stamped commit: `e5fcf1dd8c5afc80ea1f7601a64f34044750da1d` - replay comparison: no identity change (stamped SHA equals landed SHA) This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

claude referenced this pull request 2026-10-04 00:18:46 +02:00

feat(prep): a release without fragments gets its notes from feat/fix commit subjects #1529

claude referenced this pull request 2026-10-04 00:18:46 +02:00

feat(prep): a release without fragments gets its notes from feat/fix commit subjects #1529

Sign in to join this conversation.

Reviewers

No reviewers

alex

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

epic

Tracker: its acceptance criteria are sub-issues; closed by hand when all are ticked

  

kind

feature

New feature or capability

  

loop/paused

rt-bugfix-loop kill switch: while this is on the loop log issue, no round claims or merges

  

mirror-drift

Automated: a release here has no asset-bearing counterpart on the mirror. One tracker per drift episode; the check never reopens a closed one (#1586)

  

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+

  

status

blocked

Cannot start until a named dependency resolves

No labels

bump

major

bump

minor

bump

patch

kind

bug

kind

chore

kind

docs

kind

epic

kind

feature

loop/paused

mirror-drift

priority

critical

priority

high

priority

low

priority

medium

size

L

size

M

size

S

size

XL

status

blocked

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

3 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!1531

No description provided.