Release Notes Generator

Turn a raw commit list into notes a human can read in 30 seconds and act on.

When to use

Use when asked to draft release notes, update a CHANGELOG, prepare an upgrade notice or summarize what changed between two tags. Good for customer-facing announcements and internal release updates alike.

Do not use for: marketing copy that must sell a feature (this notes only what changed), a full changelog with every micro-commit, or rewriting prose the user already wrote. When a commit is ambiguous, ask rather than infer intent.

Core discipline

Group by user impact, not by how the work was structured. A commit typed chore can carry a visible behavior change; a commit typed feat can be pure plumbing. The parser is a first pass — your judgement decides the final grouping.

Separate breaking changes into their own section at the top. For every item, state the observable consequence, not the internal mechanism.

Workflow

1. Gather the commit set

Ask the user which release the notes are for and whether they need customer- or internal-facing tone. Missing a boundary tag? Ask, or use the last CHANGELOG entry as the anchor and say so.

2. Run the categorizer

python3 scripts/notes_builder.py . --from-ref v1.2.0 --to-ref v1.3.0 --format md

It parses conventional commits (feat, fix, perf, docs, refactor, test, build, ci, chore, revert), detects BREAKING CHANGE: footers and ! markers, groups by scope, and emits candidate notes. Its grouping is a draft: fix the wording and regroup by user impact yourself.

3. Regroup by user impact

Run the parser, then apply your judgement:

4. Write reader-first sections

Keep this order — most urgent to least:

1. Breaking (top, unmissable) — what breaks, who is affected, how to migrate.
2. Added — new capabilities, each a sentence a reader can understand without the codebase.
3. Fixed — the symptom and what it was fixed in.
4. Changed / Deprecated / Removed — behavior changes, rename guidance.
5. Security — the fix and the exposure, without publishing exploit detail.
6. Performance — before/after figures when known.
7. Docs / Internal — optional, compact.

Rules: verb-first bullets, no internals jargon, cite the PR/issue for each item, and never claim something was fixed unless a commit says so.

5. Verify

• Reconcile against the raw commit list — no item in, none silently merged away.
• Every breaking change is in the Breaking section and mentions a migration path.
• Security entries do not leak exploit steps.
• Date, version tag and scope of the release are stated once at the top.

Worked example

Input (git log --oneline v1.2.0..v1.3.0)

feat(api): add bulk export endpoint /v2/exports
fix(auth): session cookie now expires correctly across browsers
perf(db): cache hot reads, cut p95 from 240ms to 90ms
chore(ci): publish ARM builds of the CLI
refactor(config): rename env var DB_HOST to DATABASE_HOST (BREAKING CHANGE)
docs: add quickstart for the Python SDK

Output (regrouped)

# v1.3.0 — 2026-08-20

> Covers changes since v1.2.0. Customers upgrading from v1.2.x should read the
> breaking section first.

## Breaking
- Environment variable `DB_HOST` is renamed to `DATABASE_HOST`. Update any
  deployment that references the old name. (#82)

## Added
- Bulk export endpoint `POST /v2/exports` for pulling large datasets in one
  call. (#78)

## Fixed
- Session cookies now expire correctly across browsers; users are no longer
  logged out mid-session. (#79)

## Performance
- Hot database reads are cached: p95 latency dropped from 240 ms to 90 ms. (#80)

## Internal
- CLI publishes ARM builds. (#81)
- Added the Python SDK quickstart to the docs. (#83)

Why — the refactor that renames an env var is genuinely breaking, so it is promoted to the top despite its type; the chore that ships ARM builds stays internal because end users do not consume CI. Grouping follows user impact, not the commit type.

Quality checklist

• notes_builder.py run; output reviewed item by item, not pasted through
• Every commit in the range is accounted for (or explicitly excluded)
• Breaking changes at the top, each with a migration path
• Bullets are verb-first and readable without the codebase
• Security items omit exploit detail
• No internals jargon for customer-facing notes
• PR/issue references attached to each item
• Version, date and commit range stated at the top

Failure modes