Guide
How to Write Release Notes (Examples + Template)
To write release notes, group changes into Added, Improved, Fixed, and Removed, lead each item with the user benefit in plain language, and tag the version and date.
Updated 2026-06-30
How do you write release notes?
To write release notes, list every meaningful change since the last version, group those changes under clear headings such as Added, Improved, Fixed, and Removed, and rewrite each item so it leads with the benefit to the reader rather than the internal implementation detail. Stamp the top with the version number and release date, then keep the language plain enough that a non-technical user can understand what changed and why it matters.
Good release notes answer one question for the reader: what is different now, and what should I do about it? Everything else is secondary. The format below works for an app, an API, a library, or an internal tool, because the structure stays the same even as the audience changes.
A simple release notes template
Start from a repeatable skeleton so every release looks consistent and readers learn where to find what they care about. Copy the structure below and fill in only the sections that apply to the release.
- •Version and date: e.g. v2.4.0 — June 30, 2026.
- •One-line summary: the single most important thing in this release.
- •Added: brand-new features or capabilities.
- •Improved: changes to existing behavior, performance, or design.
- •Fixed: bugs that were resolved.
- •Removed or Deprecated: anything taken away or scheduled for removal.
- •Breaking changes: anything that requires the reader to take action, called out loudly.
Step-by-step: writing a release note
Once you have the template, the writing itself becomes a short, mechanical process. Follow these steps for each release and you will produce clear notes in minutes instead of agonizing over wording.
- 1
Gather the raw changes
Pull the list of merged pull requests, closed issues, and commits since the previous tag. This is your source material, not your final copy.
- 2
Filter out the noise
Drop internal refactors, dependency bumps, and CI tweaks that the reader cannot see. If a change has zero observable effect on the user, it usually does not belong in user-facing notes.
- 3
Group by type of change
Sort the survivors into Added, Improved, Fixed, Removed, and Breaking. Grouping lets a reader jump straight to the category they care about.
- 4
Rewrite each item benefit-first
Turn 'Refactored auth token cache' into 'You now stay logged in for 30 days instead of 24 hours.' Lead with the outcome, follow with the detail only if needed.
- 5
Flag anything that requires action
Move breaking changes to the top and state exactly what the reader must do, with a migration link if one exists.
- 6
Add the version, date, and summary line
Top the note with the version number, the release date, and a one-sentence summary so skimmers get the gist instantly.
Before and after: turning commits into notes
The biggest mistake teams make is pasting raw commit messages into the changelog. Commit messages are written for other engineers; release notes are written for users. Compare the two versions below.
Raw commit: 'fix(api): handle null cursor in paginated list endpoint'. Reader-facing note: 'Fixed an error that could occur when paging through large result sets in the API.' Same change, but the second version tells the reader what they would have experienced and confirms it is gone.
Another example. Raw commit: 'feat: add webhook retry with exponential backoff'. Reader-facing note: 'Webhooks now retry automatically with increasing delays, so a brief outage on your endpoint no longer drops events.' The benefit is the durability, not the algorithm.
How long should release notes be?
As long as they need to be and no longer. For a small patch, three bullet points is plenty. For a major version with breaking changes, you may need a short paragraph of context, a migration section, and a grouped list of everything else.
A reliable rule: every line should earn its place. If a reader would not change their behavior, file a ticket, or feel relieved after reading a line, consider cutting it. Density beats volume.
- •Patch release: 1-5 short bullets, often just the Fixed section.
- •Minor release: a summary line plus Added and Improved sections.
- •Major release: summary, breaking changes with migration steps, then the grouped detail.
Tone and style tips
Write in the present tense and the active voice: 'You can now export to CSV', not 'CSV export has been added'. Address the reader as 'you'. Keep one idea per bullet. Avoid internal codenames, ticket numbers, and jargon that only your team understands.
Consistency matters more than cleverness. Pick a voice, decide whether you capitalize headings, choose whether bullets end in periods, and then apply those choices every single release. Readers trust a changelog that looks the same every time.