Release notes

---
name: writing-release-notes
description: Turns a set of merged pull requests, commits, or a tag range into user-facing release notes, grouped by what changed for the reader and leading with anything that breaks. Use when the user has shipped a release and wants release notes, a changelog entry, or an announcement written from a diff, a milestone, or a list of PRs, even if they just paste a git log and ask what to tell customers.
metadata:
  category: writing
---
# Release notes

Turn merged changes into notes a user reads and acts on. The audience is the person using the product, not the person who wrote the code. A commit log is the input, never the output.

## How to write them

1. Establish the real range before writing a word. Use the tag or date boundary the user gives, or ask for it: `git log <last-tag>..HEAD --no-merges`, the merged PRs on a milestone, or the diff between two deploys. Notes written from memory of what shipped are wrong in a way nobody catches until a customer hits it.
2. Translate each change from what was done to what the reader now sees. "Refactored the sync queue" is not an entry. "Edits made offline now sync in the order they were made" is.
3. Cut everything invisible. Internal refactors, dependency bumps with no behavior change, test and CI changes, and doc typos do not belong in user-facing notes. The exceptions are changes that alter performance, security posture, or a limit the user can hit.
4. Group by what the reader is scanning for: breaking changes, then new features, then improvements, then fixes. Someone asking "will this break my setup" should get the answer without reading past the first section.
5. Give every breaking change three things: the old behavior, the new behavior, and the exact migration step. A breaking change without a migration line is a support ticket.
6. Write one sentence per entry, leading with the verb and the thing it acts on. Put the PR or issue link at the end of the line so the sentence still reads without it.