Release notes template¶
Copy this into the GitHub Release body for a new tag. Keep section order and headings exactly as below so notes stay skimmable across releases.
Sources to compile from:
- git log --format='%H|%an|%s' <previous-documented-tag>..<new-tag> for the raw commit list.
- Squash-merge commit subjects carry the PR number as (#NNN) - use git log -1 --format='%B' <sha>
to pull the full PR body, which usually already has a - Configuration: ... list (see
CLAUDE.md's PR-summary convention) to lift Breaking Changes bullets from directly.
- GitHub's own "Generate release notes" button (when drafting the release in the UI) produces the
## What's Changed + ## Full Changelog sections automatically from merged PRs - prefer that
over reconstructing it by hand; the manual git-log approach here is a fallback when gh/UI access
isn't available.
- Compare against the last tag that actually got documented release notes, not necessarily the
immediately preceding tag - intermediate patch tags without their own notes are folded in (see
v0.30.0...v0.40.1 in the v0.40.1 notes).
Features¶
One line per notable addition, grouped loosely by module, terse and imperative:
Only user/operator-visible capability adds belong here - internal refactors and test-only changes do not, even if they came in a big PR.
Breaking Changes¶
One ### subsection per independent breaking change (component/config-type renames, wire-shape
changes, CLI flag removals, telemetry field renames). For each:
- Say what changed (old -> new).
- Say who is affected (dashboards matching a telemetry field, triggers matching a component ref or
expr, Compose files pinning a CLI flag, hand-edited config files). - Say whether there's an automatic migration (config schema bump plus a configurer migration
step, or a retired-type rename) or whether it needs a manual fix (e.g. trigger
exprfree-form text is never migrated automatically). - Add a minimal before/after snippet only when the shape itself is non-obvious (a nested field, a renamed key) - skip it for a plain rename.
Do not list ordinary bug fixes here, even severe ones - those go in Fixes.
Fixes¶
Only pull out fixes that were user-visible or operationally significant (data loss, a stuck
retry loop, a hung config apply, a wrong status/telemetry value). Routine fixes stay implicit in
What's Changed below rather than being called out twice.
What's Changed¶
The PR list, one line per merged PR, oldest or newest first (match whatever GitHub's own generator produces - newest first):
Commits pushed directly to main without going through a PR have no (#N) in their subject and
therefore no PR link - GitHub's real auto-generated notes omit them entirely. If any exist in the
range and are worth surfacing (e.g. a doc/ADR update), list them separately under a short
"Other changes" note rather than inventing a PR link for them.