| name | release-notes |
| description | Draft user-facing release notes from a git log range. Trigger when the user asks for "release notes", "changelog entry", or "what shipped this week" with a git ref range. Output is markdown sections grouped by Features / Fixes / Breaking with PR links. |
Release Notes Drafter
Generate clear, user-facing release notes from git log between two refs.
When to fire
- User mentions: "release notes", "changelog", "what shipped", "summarize this milestone"
- A git ref range or version tag is in scope (e.g.
v1.2.0..HEAD, last-tag..main)
Inputs you should gather
- The two refs (default:
<latest tag>..HEAD if user didn't specify)
- Audience: end users (default), API consumers, internal team
- Output format: markdown (default), JSON, or plain text
Steps
- Run
git log <from>..<to> --pretty=format:'%h%x09%s%x09%an' --no-merges
- For each commit, classify:
feat: / add: → Featuresfix: / bugfix: → FixesBREAKING CHANGE: (in body) → Breaking (top of doc, explicit migration note)- everything else (
chore:, docs:, refactor:, test:) → omit unless user-visible
- For each entry, rewrite the commit message in user-facing language (no
feat(api): prefix; no internal jargon)
- If there's a PR number in the commit (
(#1234)), link it
- Group by category, sort by impact (breaking > features > fixes > minor)
Output template
## <version> — <date>
### ⚠️ Breaking changes
- <one-sentence summary>. **Migration:** <what to do>. ([#PR])
### ✨ Features
- <user-visible benefit>. ([#PR])
### 🐛 Fixes
- <symptom that's now fixed>. ([#PR])
Gotchas
- Don't dump raw commit messages — rewrite from the user's perspective
- Squash-merged repos: each merge commit covers many internal commits; read the PR description for context
- Conventional Commit
chore: and docs: rarely belong in user-facing notes
- If
BREAKING CHANGE: is in the body of a feat:, the entry must surface as Breaking, not Feature
- For monorepos, prefix entries with the affected package name (
[@org/auth])
References
- See
references/conventional-commits.md for the full type list
- See
examples/v1.2.0.md for a polished sample
