Release notes template
Release notes announce one specific release in plain language — what changed, who it affects, and what to do next. Ask your agent to draft them, share the link, and comments land on the exact entry.
Good release notes answer three questions in under 30 seconds: what changed, does it affect me, and what do I need to do? Most fail because they're written as commit logs for an engineering audience and then handed to users who don't know what a "refactor" means or why they should care.
Draft them with your agent
Paste this into Claude, Cursor, or any agent — it drafts the release notes and publishes them as a Drafty link:
See it on a real one
What goes in a release notes template
Four sections cover almost every release:
- Version + date — what shipped and when. Use a specific date (2025-01-15), not "this week" — users reading these three months later need context.
- What's new — net-new capabilities. Lead with the highest-impact change, not alphabetical order. One heading + one sentence per feature; if it needs three paragraphs, it needs its own help article.
- Improvements — changes to existing behavior that make things better: faster load, clearer error messages, a form that no longer times out. Include a before/after if the difference is subtle.
- Bug fixes — what was broken and is now fixed, in user terms. "Fixed a bug that logged some users out unexpectedly on mobile" is correct. "Fixed edge case in auth token refresh" is a commit message, not a release note.
The most common mistake: treating a release as a list of tasks your team completed instead of a list of outcomes your users get. Every line in your release notes should be answerable with "so you can now…" — if it isn't, cut it or rewrite it.
The section most teams skip
Add a short "not in this release" note for anything users were expecting. If a frequently-requested feature got pushed, a single line — "bulk export is coming in the next release" — prevents a wave of support questions. The absence of something people expected is news too.
When release notes and a changelog are different tools
A changelog is the cumulative record — every release, going back to day one, reverse-chronological. Users who want the full history go there.
Release notes are the announcement for one release. They're more contextual: screenshots, migration steps, and a plain-language summary aimed at the user who got a notification that a new version dropped and wants to know if they should care.
If you're writing something with a specific version number that you'll email, post in-app, or put in the App Store, that's release notes. If it's a running log your changelog page hosts, that's a changelog.
FAQ
What format should release notes follow?
Short headings with an action verb, one-to-two sentences of context per entry, and category labels (New, Improved, Fixed) so users can scan for what affects them. Group by category, not by component — users think in jobs, not system architecture.
How long should release notes be?
A minor patch: three to eight bullet points. A major release: a short summary paragraph, then the categorized list, then any migration steps. If it runs past 400 words, move the detail into documentation and link to it — the notes should scan in under a minute.
What's the difference between release notes and release documentation?
Release notes are the announcement — what changed and why it matters to you. Release documentation is the reference material: API specs, migration guides, configuration options. The notes say "you can now do X"; the docs say "here's exactly how."
Who should write release notes?
Usually the PM or the person closest to users — not the engineer who built the feature. Engineers write for precision; release notes need to be written for someone who hasn't been in the sprint meetings. The best workflow: engineering describes what changed, the PM rewrites it in user terms.
Should release notes include screenshots?
Yes, for any UI change. A screenshot or short screen recording communicates a layout change faster than a paragraph can. For API or infrastructure changes, skip the image — add a code snippet if the change requires a configuration update.
Do release notes need to mention every change?
No. Skip internal tooling changes, refactors that don't affect behavior, and dependency updates with no user-visible effect. The filter is simple: if a user can't observe the change, it doesn't belong in the release notes. If you're unsure, leave it out — users will notice if you're burying the important things in noise.