Raw view: Release notes from merged PRs since last tag
No invisible, zero-width, or bidi-control characters detected.
---
name: release-notes
description: Turns the merged pull requests and commits since the last git tag into user-facing release notes grouped by impact (breaking, new, improved, fixed, security, internal), with upgrade steps. Use when the user asks to write release notes, draft a changelog entry for a version, prepare a GitHub release, or summarize what shipped since the last release.
license: CC0-1.0
allowed-tools: Bash(git tag *) Bash(git describe *) Bash(git log *) Bash(gh pr list *) Bash(gh pr view *) Bash(gh release *)
metadata:
author: Waxmark
version: "1.0.0"
---
# Release Notes
Release notes are written for the person upgrading, not the person who wrote the code. Every line answers "what changes for me?"
## Procedure
1. **Find the range.**
```bash
LAST=$(git describe --tags --abbrev=0)
echo "$LAST"
git log --oneline --merges "$LAST"..HEAD
git log --oneline --no-merges "$LAST"..HEAD
```
If there is no tag, ask for the previous release commit or date. If the repo squash-merges, the non-merge log is the PR list.
2. **Pull PR metadata** when `gh` is available; PR titles and labels are usually better than commit subjects.
```bash
gh pr list --state merged --search "merged:>$(git log -1 --format=%cI "$LAST")" --limit 200 \
--json number,title,labels,author,body,url
```
For PRs whose title is unclear, read the body with `gh pr view <n> --json body`.
3. **Classify** each item into exactly one section. Decide by user impact, not by commit type: a `refactor` that changes a default is **Breaking**; a `feat` that only adds an internal metric is **Internal**.
4. **Rewrite** each line in the user's vocabulary. Start with the capability or the problem, not the implementation. Drop PR noise ("bump", "wip", "fix lint") into Internal or omit.
5. **Write upgrade steps** for every Breaking item: what to change, with a before/after snippet when it fits on two lines.
6. **Verify** by re-reading the merge list: every PR is either in the notes or consciously omitted. Count both and report.
## Output template
```markdown
# <project> <version> - <YYYY-MM-DD>
<One or two sentences: the theme of this release and the headline change.>
## Breaking changes
- **<What breaks>.** <Why.> Upgrade: <exact step>. (#123)
## New
- <Capability, from the user's point of view>. (#124)
## Improved
- <Existing behavior, now better how>. (#125)
## Fixed
- <Symptom the user saw> no longer happens when <condition>. (#126)
## Security
- <Issue class> in <component>; <versions affected>; <CVE or advisory id if any>. (#127)
## Internal
- <Dependency bumps, CI, refactors - one line each or a single summary line>
## Upgrade notes
1. <Ordered steps, including migrations and config changes>
Full diff: <compare URL, e.g. https://github.com/OWNER/REPO/compare/<last>...<new>>
Contributors: @a, @b (first-time: @c)
```
Omit empty sections. Keep each bullet to one sentence; link the PR number at the end.
## Style rules
- Present tense, active voice: "Exports now include archived items", not "Added support for exporting archived items".
- Name the user-visible surface (CLI flag, API field, UI screen), not the file or function.
- Numbers over adjectives: "Cold start drops from 3.1s to 0.9s", not "much faster".
- Version bump suggestion: Breaking -> major, New -> minor, otherwise patch (for pre-1.0 projects, Breaking -> minor). State it with the reason.
## Example line rewrites
| Commit / PR title | Release note |
|---|---|
| `fix(parser): handle CRLF in frontmatter` | Files with Windows line endings no longer fail to parse frontmatter. (#88) |
| `feat: add --json flag to list cmd` | `list --json` prints machine-readable output for scripting. (#91) |
| `refactor: default timeout 30s -> 10s` | **Default request timeout is now 10s** (was 30s). Upgrade: set `timeout: 30000` to keep the old behavior. (#95) |