Writing Release Notes
Overview
Summarize shipped changes in a way that is accurate, scannable, and appropriate for the intended audience (internal, customers, or both).
When to Use
- A set of PRs/issues is ready for release and needs a coherent summary
- Stakeholders need to know impact, risk, and required follow-ups
- You must communicate changes without leaking sensitive/internal details
When NOT to use
- No user-visible or operationally relevant changes occurred
Core Pattern
Write for outcomes, not implementation:
- What changed (user-facing)
- Who is affected (segments, plans, roles)
- Anything required (migration steps, toggles, downtime)
- Known issues (if applicable)
Quick Reference
Use this structure:
- Highlights (2–5 bullets)
- Improvements
- Fixes
- Breaking changes (if any) + mitigation
- Operational notes (deploy windows, feature flags) (internal-only)
Implementation
- List included tickets/PRs and group by theme.
- Rewrite each item as “Outcome + affected area” in plain language.
- Add any required actions and clearly label breaking changes.
- Remove internal-only details (stack traces, customer names, security-sensitive info).
Common Mistakes
- Changelog dump: raw PR titles are rarely meaningful—rewrite.
- Overclaiming: avoid “fixed forever”; be precise about scope.
- Missing required actions: if users must do something, put it near the top.