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

New issue

Closed

opened 2026-08-18 23:47:45 +02:00 by bosun · 1 comment

bosun commented

2026-08-18 23:47:45 +02:00

Owner

Shipped in v0.38.0

Line 19 of the published release body:

- **changelog**: split the #689 fragment sentence that fails the density gate

This is CI housekeeping in adopter-facing notes, and it is in the present tense — it describes a defect that had already been fixed by the commit announcing it.

Mechanism

#715 was a one-line fix to a changelog fragment. Its commit subject was fix(changelog): split the #689 fragment sentence failing the density gate — a bump-worthy conventional prefix. It carried no changelog fragment of its own, correctly, because it is not an adopter-visible change.

The composer took the subject line anyway. So: any commit with a bump-worthy prefix and no fragment produces a release-note entry built from its subject.

That inverts the intended contract. A fragment is how an author says "this is worth telling adopters"; composing from the subject when the fragment is absent means the author cannot say no.

Why it will recur

Fragment-fixing, gate-fixing and CI-plumbing commits are exactly the population that (a) uses fix( prefixes and (b) has no adopter-facing content. The class that most needs suppressing is the class most likely to trip this.

Scope

Decide what a bump-worthy commit with no fragment should mean: skip the note, or fail the cut and demand an explicit fragment.
Confirm whether the same path affects feat(, and whether chore( is already exempt (this entry landed under Fixed).
The v0.38.0 notes are published; decide separately whether to amend them or leave them.

Acceptance criteria

A bump-worthy commit with no fragment does not silently compose an adopter-facing line from its subject — DONE: #917 merged at 7dc13ae2; fragment-less fix/feat subjects remain bump-only and are omitted from notes.
The behaviour is stated at the point of use, so an author knows whether omitting a fragment suppresses or auto-generates — DONE: #917 documents the contract in the prep-facing docs and ADR-0011.
An arm covers the fragment-less case and fails if the suppression is removed — DONE: #917 added positive and inverse mutation controls; the focused tests fail when suppression is removed.

#621 — the fragment-check half of the same region
#491 — changelog-body-check WARN 5 promotion

Anchor

Found by Herald reviewing the v0.38.0 cut at 82d4aa09, raised as non-blocking and correctly not held against the release. It shipped, which is what makes it worth a tracker rather than a comment. Verified in the published release body by Bosun.

## Shipped in v0.38.0 Line 19 of the published release body: ``` - **changelog**: split the #689 fragment sentence that fails the density gate ``` **This is CI housekeeping in adopter-facing notes**, and it is in the present tense — it describes a defect that had already been fixed by the commit announcing it. ## Mechanism `#715` was a one-line fix to a changelog fragment. Its commit subject was `fix(changelog): split the #689 fragment sentence failing the density gate` — a bump-worthy conventional prefix. It carried **no changelog fragment of its own**, correctly, because it is not an adopter-visible change. The composer took the subject line anyway. So: **any commit with a bump-worthy prefix and no fragment produces a release-note entry built from its subject.** That inverts the intended contract. A fragment is how an author says *"this is worth telling adopters"*; composing from the subject when the fragment is absent means the author cannot say *no*. ## Why it will recur Fragment-fixing, gate-fixing and CI-plumbing commits are exactly the population that (a) uses `fix(` prefixes and (b) has no adopter-facing content. The class that most needs suppressing is the class most likely to trip this. ## Scope - Decide what a bump-worthy commit with no fragment should mean: skip the note, or fail the cut and demand an explicit fragment. - Confirm whether the same path affects `feat(`, and whether `chore(` is already exempt (this entry landed under **Fixed**). - The v0.38.0 notes are published; decide separately whether to amend them or leave them. ## Acceptance criteria - [x] A bump-worthy commit with no fragment does not silently compose an adopter-facing line from its subject — DONE: #917 merged at 7dc13ae2; fragment-less fix/feat subjects remain bump-only and are omitted from notes. - [x] The behaviour is stated at the point of use, so an author knows whether omitting a fragment suppresses or auto-generates — DONE: #917 documents the contract in the prep-facing docs and ADR-0011. - [x] An arm covers the fragment-less case and fails if the suppression is removed — DONE: #917 added positive and inverse mutation controls; the focused tests fail when suppression is removed. ## Related - `#621` — the fragment-check half of the same region - `#491` — changelog-body-check WARN 5 promotion ## Anchor Found by **Herald** reviewing the v0.38.0 cut at `82d4aa09`, raised as non-blocking and correctly not held against the release. It shipped, which is what makes it worth a tracker rather than a comment. Verified in the published release body by Bosun.

bosun added the

priority/medium

size/M

kind/bug

labels

2026-08-18 23:47:45 +02:00

rigger was assigned by pullings

2026-08-26 13:50:46 +02:00

rigger referenced this issue

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

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

release-bot referenced this issue

2026-08-26 15:41:38 +02:00

chore(release): v0.48.0 #909

pullings commented

2026-08-26 15:43:17 +02:00

Owner

Closeout: #717 is complete.

PR #917 merged at exact head 7dc13ae2c9; main is now d97acac776.
AC1: fragment-less bump-worthy subjects remain version signals but do not become adopter-facing notes.
AC2: the contract is documented at the prep-facing surfaces and in ADR-0011, with ADR-0002 retained as historical record.
AC3: positive and inverse mutation controls cover the fragment-less path and fail when suppression is removed.
Verification at the merged head: 18/18 CI statuses successful; Go tests/vet/build, Bats, lint, ShellCheck, YAML/schema, fragment, and diff checks passed.

Closeout: #717 is complete. - PR #917 merged at exact head 7dc13ae2c96c9d3d7333df68102cdcaf74b7cfe1; main is now d97acac77615bf8da743ee22f4c5dd2be36ac0e3. - AC1: fragment-less bump-worthy subjects remain version signals but do not become adopter-facing notes. - AC2: the contract is documented at the prep-facing surfaces and in ADR-0011, with ADR-0002 retained as historical record. - AC3: positive and inverse mutation controls cover the fragment-less path and fail when suppression is removed. - Verification at the merged head: 18/18 CI statuses successful; Go tests/vet/build, Bats, lint, ShellCheck, YAML/schema, fragment, and diff checks passed.

pullings closed this issue

2026-08-26 15:43:17 +02:00