release: notes surface every breaking change, and a break must carry the ! marker #719

New issue

Open

opened 2026-10-05 14:54:42 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-05 14:54:42 +00:00

Owner

What happens

The release notes group commits by type (Features, Bug Fixes, and so on) in .goreleaser.yaml:146-165. No group collects breaking changes, and nothing in the notes flags one. The group patterns tolerate the ! marker but do not key on it (for example '^feat(\([^)]*\))?!?:' at .goreleaser.yaml:148), so a feat!: lands in Features and reads like any feature. A BREAKING CHANGE: footer never shows, because the groups match the subject line only.

v0.20.0 carries every breaking change to the ADR tooling at once (#675). Its notes must tell a reader what broke and what to do. Today they would not.

What I want

A "Breaking changes" changelog group, ordered first, matching the !: subject form, that collects every breaking commit.
A gate check that fails when the public API surface (as the parity test in internal/parity/ defines it) changes in the unreleased range and no commit carries the ! marker. This keeps the group complete and stops the version bump under-counting a break.
A migration section in the notes. A release preflight fails the cut when the range holds breaking commits but no migration section is supplied. It is read-only, prints each problem, and aborts before the tag is pushed, the same shape as scripts/check-satellite-readiness.sh.

Acceptance criteria

The changelog renders a "Breaking changes" section first, listing every !: commit in the range.
./scripts/gate.sh fails a public-API change whose subject has no ! marker, and names the commit.
./scripts/release.sh aborts before the tag push when the range has breaking commits and no migration section, and names what is missing.
A release with no breaking commits is unchanged in all three paths.

Refs #675.

## What happens The release notes group commits by type (Features, Bug Fixes, and so on) in `.goreleaser.yaml:146-165`. No group collects breaking changes, and nothing in the notes flags one. The group patterns tolerate the `!` marker but do not key on it (for example `'^feat(\([^)]*\))?!?:'` at `.goreleaser.yaml:148`), so a `feat!:` lands in Features and reads like any feature. A `BREAKING CHANGE:` footer never shows, because the groups match the subject line only. v0.20.0 carries every breaking change to the ADR tooling at once (#675). Its notes must tell a reader what broke and what to do. Today they would not. ## What I want 1. A "Breaking changes" changelog group, ordered first, matching the `!:` subject form, that collects every breaking commit. 2. A gate check that fails when the public API surface (as the parity test in `internal/parity/` defines it) changes in the unreleased range and no commit carries the `!` marker. This keeps the group complete and stops the version bump under-counting a break. 3. A migration section in the notes. A release preflight fails the cut when the range holds breaking commits but no migration section is supplied. It is read-only, prints each problem, and aborts before the tag is pushed, the same shape as `scripts/check-satellite-readiness.sh`. ## Acceptance criteria - The changelog renders a "Breaking changes" section first, listing every `!:` commit in the range. - `./scripts/gate.sh` fails a public-API change whose subject has no `!` marker, and names the commit. - `./scripts/release.sh` aborts before the tag push when the range has breaking commits and no migration section, and names what is missing. - A release with no breaking commits is unchanged in all three paths. Refs #675.

hexajon added a new dependency

2026-10-05 14:56:38 +00:00

#675 epic: v0.20.0 - breaking: clearer ADR tooling and the write guard on every surface

hexajon referenced this issue

2026-10-05 15:05:31 +00:00

docs(adr): record the release-notes and attribution gates as 0050 and 0051 #722

hexajon referenced this issue from a commit

2026-10-05 15:05:32 +00:00

docs(adr): add proposed 0050 and 0051 for release-notes and attribution gates

hexajon removed a dependency

2026-10-18 05:21:48 +00:00

#675 epic: v0.20.0 - breaking: clearer ADR tooling and the write guard on every surface