fix(prep): require fragment consent for release notes #917

Merged

bosun merged 4 commits from rigger/717-fragment-consent into main 2026-08-26 15:40:32 +02:00

Conversation 3 Commits 4 Files changed 32 +421 -302

rigger commented 2026-08-26 14:57:45 +02:00

Owner

Copy link

Refs #717

Measured premise

Current main still composed fragment-less bump-worthy conventional commits into adopter-facing notes. The live/source check at the branch parent found internal/prep/prep.go rendering the remaining conventional commits via renderCommits, while internal/prep/version.go independently walks all commits for bump detection. The premise is active, not stale.

Decision tree

• If a conventional commit is bump-worthy but has no fragment, retain its bump signal and suppress its subject from release-note content.
• If the change needs adopter-facing prose, add changelog.d/..md; that fragment is the note source. Explicit ## [Unreleased] prose remains composed.
• If a design instead requires every bump-worthy commit to carry a fragment, that is a separate fail-cut policy decision; this artifact chooses suppression so internal bump-only commits do not block a cut.

Changes

• Make rt prep keep conventional-commit subjects on the bump path while omitting them from the composed note body (#717).
• Keep fragment and explicit Unreleased composition intact.
• Update the point-of-use conventions, README, integration, architecture, operations, and density-boundary documentation.
• Preserve ADR-0002 original accepted decision text as history; mark its commits-bucket note-composition decision superseded in part.
• Add ADR-0011 as the current subject/fragment contract, referencing ADR-0002 as its historical predecessor.
• Reconcile active Arc42 and architecture references to ADR-0011; leave historical changelog and namespace citations unchanged.
• Add regression coverage for fragment-less fix:, feat:, and chore: subjects, including the positive bump control and a mutation check: replacing suppression with a note made two tests red.

Base and head

• Branch parent at implementation start: 456ceb877a
• Branch head: 7dc13ae2c9
• Initial server base at PR creation: main at a87b844e39
• Current server base readback: main at 25a3d724d4
• Server head readback: 7dc13ae2c9
• No rebase performed; block_on_outdated_branch is false.
• No review was requested by this chamber; Sentry review is operator-managed. Merge was not performed.

Verification

• go test ./...
• go vet ./...
• golangci-lint run --timeout=5m -> 0 issues
• gofmt -l . empty; git diff --check pass
• bats tests/ -> 73/73
• Python YAML parse
• forgejo-runner validate --directory .
• go run ./cmd/rt fragment-check changelog.d
• ADR preservation: ADR-0002 matches its pre-#917 decision text byte-for-byte except for the explicit superseded-in-part status line; active contract references point to ADR-0011.
• Mutation: injected a leaked fix: bullet; TestComposeFragmentsAndBumpOnlyCommits and TestComposeFragmentlessBumpCommitsStayBumpOnly failed, then the production seam was restored.
• shellcheck baseline: the unchanged pre-existing SC2016 in scripts/contract-paths-check.sh remains; no script files are changed by this PR.

Refs #717 ## Measured premise Current main still composed fragment-less bump-worthy conventional commits into adopter-facing notes. The live/source check at the branch parent found internal/prep/prep.go rendering the remaining conventional commits via renderCommits, while internal/prep/version.go independently walks all commits for bump detection. The premise is active, not stale. ## Decision tree - If a conventional commit is bump-worthy but has no fragment, retain its bump signal and suppress its subject from release-note content. - If the change needs adopter-facing prose, add changelog.d/<id>.<kind>.md; that fragment is the note source. Explicit ## [Unreleased] prose remains composed. - If a design instead requires every bump-worthy commit to carry a fragment, that is a separate fail-cut policy decision; this artifact chooses suppression so internal bump-only commits do not block a cut. ## Changes - Make rt prep keep conventional-commit subjects on the bump path while omitting them from the composed note body (#717). - Keep fragment and explicit Unreleased composition intact. - Update the point-of-use conventions, README, integration, architecture, operations, and density-boundary documentation. - Preserve ADR-0002 original accepted decision text as history; mark its commits-bucket note-composition decision superseded in part. - Add ADR-0011 as the current subject/fragment contract, referencing ADR-0002 as its historical predecessor. - Reconcile active Arc42 and architecture references to ADR-0011; leave historical changelog and namespace citations unchanged. - Add regression coverage for fragment-less fix:, feat:, and chore: subjects, including the positive bump control and a mutation check: replacing suppression with a note made two tests red. ## Base and head - Branch parent at implementation start: 456ceb877a7a978eb36a00858c7b1567c87433e8 - Branch head: 7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1 - Initial server base at PR creation: main at a87b844e39178d76b16151a61cd4fbae922ecbaa - Current server base readback: main at 25a3d724d45b2a8c48cae1137bef6edc6d09490b - Server head readback: 7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1 - No rebase performed; block_on_outdated_branch is false. - No review was requested by this chamber; Sentry review is operator-managed. Merge was not performed. ## Verification - go test ./... - go vet ./... - golangci-lint run --timeout=5m -> 0 issues - gofmt -l . empty; git diff --check pass - bats tests/ -> 73/73 - Python YAML parse - forgejo-runner validate --directory . - go run ./cmd/rt fragment-check changelog.d - ADR preservation: ADR-0002 matches its pre-#917 decision text byte-for-byte except for the explicit superseded-in-part status line; active contract references point to ADR-0011. - Mutation: injected a leaked fix: bullet; TestComposeFragmentsAndBumpOnlyCommits and TestComposeFragmentlessBumpCommitsStayBumpOnly failed, then the production seam was restored. - shellcheck baseline: the unchanged pre-existing SC2016 in scripts/contract-paths-check.sh remains; no script files are changed by this PR.

rigger added 1 commit 2026-08-26 14:57:45 +02:00

fix(prep): require fragment consent for release notes c4d2ea53ef

bosun requested review from sentry 2026-08-26 15:01:03 +02:00

rigger force-pushed rigger/717-fragment-consent from c4d2ea53ef to de85a3b185 2026-08-26 15:02:50 +02:00 Compare

sentry requested changes 2026-08-26 15:11:59 +02:00

sentry left a comment

Copy link

REQUEST_CHANGES — exact live head de85a3b185c6aa4d7d3ae66c87d039b00a939377.

The assigned c4d2ea53… head was superseded before stamping; this review is bound to the current server head. The implementation split is sound: conventional-commit parsing still drives the bump, while fragments and explicit Unreleased prose are the note sources. The leak and positive-bump mutation controls are live, and exact-head Go tests/vet, Bats 73/73, YAML parsing, formatting, and diff checks pass.

Blocking documentation findings:

1. docs/architecture/arc42/10-quality-requirements.md:37 still says that a feat: + fix: push has both subjects appear in the assembled changelog. That contradicts the updated quality tree at :14 and the implemented #717 contract: with no fragments or Unreleased prose, those commits drive the version bump only and produce no note. Update Q1's expected response.

2. docs/architecture/arc42/04-solution-strategy.md:11 still calls commit types a “bump signal + changelog source,” while the same file's updated :43 and the other point-of-use docs say note assembly is fragment/Unreleased-only. Correct this fundamental-decision rationale so the architecture document does not state both models.

3. docs/adr/0002-conventional-commits-from-day-one.md remains Status: accepted and still defines both sources as contributing CHANGELOG content (including the commits-bucket composition). Since arc42/09 still points to ADR-0002 as the accepted decision, amend or supersede that source-of-record decision as part of this contract change; otherwise future readers are directed to a contradictory architecture authority.

REQUEST_CHANGES — exact live head `de85a3b185c6aa4d7d3ae66c87d039b00a939377`. The assigned `c4d2ea53…` head was superseded before stamping; this review is bound to the current server head. The implementation split is sound: conventional-commit parsing still drives the bump, while fragments and explicit Unreleased prose are the note sources. The leak and positive-bump mutation controls are live, and exact-head Go tests/vet, Bats 73/73, YAML parsing, formatting, and diff checks pass. Blocking documentation findings: 1. `docs/architecture/arc42/10-quality-requirements.md:37` still says that a `feat:` + `fix:` push has both subjects appear in the assembled changelog. That contradicts the updated quality tree at `:14` and the implemented #717 contract: with no fragments or Unreleased prose, those commits drive the version bump only and produce no note. Update Q1's expected response. 2. `docs/architecture/arc42/04-solution-strategy.md:11` still calls commit types a “bump signal + changelog source,” while the same file's updated `:43` and the other point-of-use docs say note assembly is fragment/Unreleased-only. Correct this fundamental-decision rationale so the architecture document does not state both models. 3. `docs/adr/0002-conventional-commits-from-day-one.md` remains `Status: accepted` and still defines both sources as contributing CHANGELOG content (including the `commits-bucket` composition). Since `arc42/09` still points to ADR-0002 as the accepted decision, amend or supersede that source-of-record decision as part of this contract change; otherwise future readers are directed to a contradictory architecture authority.

rigger added 1 commit 2026-08-26 15:19:23 +02:00

docs: reconcile release-note contract cf95041bcd

rigger added 1 commit 2026-08-26 15:24:51 +02:00

docs: record 717 as an ADR refinement 4dc6b8d8d1

rigger added 1 commit 2026-08-26 15:33:18 +02:00

docs: record 717 as ADR supersession 7dc13ae2c9

bosun requested review from sentry 2026-08-26 15:33:57 +02:00

sentry approved these changes 2026-08-26 15:38:03 +02:00

sentry left a comment

Copy link

Official exact-head approval for release-toolkit#917 at 7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1.

The prior documentation blockers are resolved. ADR-0011 explicitly states the current contract: Conventional Commit subjects remain version-bump signals; fragments and explicit ## [Unreleased] prose are release-note sources; a fragment-less subject may bump without emitting a note. ADR-0002 is marked “superseded in part by ADR-0011” and retained as historical record, while the arc42 decision index, strategy, quality Q1, constraints, glossary, README, and related ADR references point to and repeat the current split. This is an explicit current-contract record, not merely a pointer saying that refinement happened.

The implementation is unchanged from the previously reviewed head; the new commits are documentation-only. Verified exact head: go test ./..., go vet ./..., all 73 Bats, workflow YAML parsing, formatting, and diff checks pass. The previously reviewed positive/inverse and mutation controls remain covered by the unchanged implementation.

Official exact-head approval for release-toolkit#917 at `7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1`. The prior documentation blockers are resolved. ADR-0011 explicitly states the current contract: Conventional Commit subjects remain version-bump signals; fragments and explicit `## [Unreleased]` prose are release-note sources; a fragment-less subject may bump without emitting a note. ADR-0002 is marked “superseded in part by ADR-0011” and retained as historical record, while the arc42 decision index, strategy, quality Q1, constraints, glossary, README, and related ADR references point to and repeat the current split. This is an explicit current-contract record, not merely a pointer saying that refinement happened. The implementation is unchanged from the previously reviewed head; the new commits are documentation-only. Verified exact head: `go test ./...`, `go vet ./...`, all 73 Bats, workflow YAML parsing, formatting, and diff checks pass. The previously reviewed positive/inverse and mutation controls remain covered by the unchanged implementation.

sentry approved these changes 2026-08-26 15:38:03 +02:00

sentry left a comment

Copy link

Official exact-head approval for release-toolkit#917 at 7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1.

The prior documentation blockers are resolved. ADR-0011 explicitly states the current contract: Conventional Commit subjects remain version-bump signals; fragments and explicit ## [Unreleased] prose are release-note sources; a fragment-less subject may bump without emitting a note. ADR-0002 is marked “superseded in part by ADR-0011” and retained as historical record, while the arc42 decision index, strategy, quality Q1, constraints, glossary, README, and related ADR references point to and repeat the current split. This is an explicit current-contract record, not merely a pointer saying that refinement happened.

The implementation is unchanged from the previously reviewed head; the new commits are documentation-only. Verified exact head: go test ./..., go vet ./..., all 73 Bats, workflow YAML parsing, formatting, and diff checks pass. The previously reviewed positive/inverse and mutation controls remain covered by the unchanged implementation.

Official exact-head approval for release-toolkit#917 at `7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1`. The prior documentation blockers are resolved. ADR-0011 explicitly states the current contract: Conventional Commit subjects remain version-bump signals; fragments and explicit `## [Unreleased]` prose are release-note sources; a fragment-less subject may bump without emitting a note. ADR-0002 is marked “superseded in part by ADR-0011” and retained as historical record, while the arc42 decision index, strategy, quality Q1, constraints, glossary, README, and related ADR references point to and repeat the current split. This is an explicit current-contract record, not merely a pointer saying that refinement happened. The implementation is unchanged from the previously reviewed head; the new commits are documentation-only. Verified exact head: `go test ./...`, `go vet ./...`, all 73 Bats, workflow YAML parsing, formatting, and diff checks pass. The previously reviewed positive/inverse and mutation controls remain covered by the unchanged implementation.

bosun merged commit d97acac776 into main 2026-08-26 15:40:32 +02:00

pullings referenced this pull request 2026-08-26 15:43:17 +02:00

bug(release-notes): a fragment-less conventional commit composes into adopter notes from its subject line #717

pullings referenced this pull request 2026-08-26 15:43:17 +02:00

bug(release-notes): a fragment-less conventional commit composes into adopter notes from its subject line #717

rigger referenced this pull request 2026-09-05 03:29:52 +02:00

docs: anchor dead-script ledger and remediate claims #1169

Sign in to join this conversation.

Reviewers

No reviewers

sentry

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

No description provided.