How to write release notes people actually read
6 min read updated
To write release notes people read, answer one question per entry: what can the reader do now that they could not do before, and what do they have to do about it. Put anything with a deadline first, name who is affected, say “no action needed” when it is true, and skip releases that have nothing to say. Everything else on this page is that rule applied.
Bug fixes and performance improvements.
Every product has shipped this. The cause is rarely laziness: this is what you get when release notes are written from the inside, by someone who has spent two weeks in the diff and can no longer see which parts of it a stranger would care about. A better tone of voice will not fix it; answering the question will.
What should release notes include?
Release notes should include, for each change worth mentioning: what the reader can now do, who it applies to, what they must do about it (including “nothing”), and when anything with a deadline takes effect. They should not include internal ticket numbers, component names only the team uses, or a version number as the only headline.
| Include | Leave out |
|---|---|
| The outcome, in the reader’s terms | The implementation, in the team’s terms |
| Who is affected, by plan, role or API version | “Some users” |
| The required action, or “no action needed” | Silence, which readers fill with the worst case |
| A date for anything with a deadline | A version number standing in for a date |
| A link to the doc that explains it | A link to the pull request |
| Fixes people reported, and the limit that was raised | Internal ticket ids |
| The boring section, one line each, at the bottom | The boring section mixed in with the news |
The split between a release note and a changelog entry is what makes this list possible: the changelog keeps everything, so the notes can leave things out. Annotated samples of each entry type are collected in release notes examples.
The question every entry answers
What can the reader do now that they could not do before, and what do they have to do about it?
If an entry cannot answer that, it belongs in the changelog and not in the release notes. Both halves matter. The first half is the value. The second half is the part teams forget, and it is the one that generates support tickets when it is missing.
Two examples of the second half doing real work:
- “Existing webhooks keep working until 1 November. After that, unsigned payloads are rejected.”
- “No action needed. Existing exports are re-encoded automatically the next time you open them.”
The second one says “no action needed” explicitly. That sentence is worth writing every single time, because a reader who cannot find it assumes the worst.
How should release notes be ordered?
Order them by consequence to the reader, never by the part of the system that changed. Grouping by API, dashboard, mobile and infrastructure is your org chart, not the reader’s problem.
- Breaking changes and anything with a deadline. First, always, even if it is small. If a reader stops after one line, this is the line they must have read. If the deadline is a sunset, the entry should read like a deprecation notice.
- What is new that they will want. One per paragraph, with the outcome in the first clause.
- What got better. Fixes that were reported, limits that were raised, things that were slow.
- Everything else, as a list. Dependency bumps, internal refactors, minor copy. One line each. Nobody reads this section, and it should still be there, because the person looking for it really needs it.
The rewrite
Before:
v4.2.0 Fixed an issue where the
POST /exportsendpoint would intermittently return 500 under load. Refactored the export worker. Bumpednode-pgto 8.11. Improved error handling in the CSV serializer.
After:
Exports no longer fail on large accounts. Accounts over roughly 50,000 rows could get a 500 when starting an export, more often at month end. That is fixed, and exports of any size now retry themselves rather than failing. No action needed, and any export that failed in the last week can simply be run again.
Also in 4.2.0:
node-pg8.11, clearer CSV serializer errors.
Same release. The second one names the account that was affected, the time it was worst, what changed, and what to do. The dependency bump did not disappear, it just stopped being the headline. The release notes best practices article has the rest of the rules the rewrite is following, each with what it costs to skip.
Things worth deleting
- “We are excited to announce.” The reader is not excited yet. Earn it in the sentence after.
- Internal ticket numbers.
PROJ-4471means nothing outside your tracker. If the entry needs a reference, link the docs page. - Component names only your team uses. If you renamed the “ingest pipeline”, say “imports”.
- A version number as the only headline.
v4.2.0is a filing label, not a summary. - Screenshots of a settings page nobody has visited. Show the thing that changed, in use.
How often should you publish release notes?
Publish when something happened, not on a schedule. Notes that arrive for every release train everyone to ignore them. Notes that arrive when something happened get opened. It is fine, and usually correct, to ship a release with no notes at all and roll its entries into the next set that has a headline worth reading.
The changelog still records all of it. That is the division of labour: the changelog is complete, the notes are selective. If you keep the changelog structured as you go, writing the notes is selection and rewriting rather than archaeology.
The release notes template is the shape we use for the selection step, and changelog examples collects entries from teams whose changelog is good enough to derive notes from.
All of this assumes a page you control, with no length limit and working links. Release notes for mobile apps covers what changes when the surface is an App Store or Play Store listing instead. Emergency release notes covers the other exception: what changes when there’s no time left to run the normal drafting process at all.
One test before you publish
Read the notes as someone who has been on holiday for two weeks and has 40 seconds. If, in that time, they cannot tell whether anything is required of them, the notes are not finished, however accurate they are. For the wider picture of what software release notes are and the four audiences they serve, see software release notes.
FAQ
How long should release notes be? As long as the consequential changes need, and no longer. A release with one breaking change and two improvements is three paragraphs. Padding a quiet release to look substantial is how readers learn to skip the notes.
Who should write release notes? The person who understands the change, edited by someone who does not. The engineer knows what changed; the editor knows what a stranger will misread. Writing the entry at merge time, while the engineer still remembers, is the practice that makes this cheap.
Should release notes include bug fixes? Yes, the ones someone reported or hit. State the symptom the reader saw, not the cause. “Exports over 50,000 rows failed” is a bug fix a reader recognises; “fixed a race in the export worker” is a commit message.
What is the difference between release notes and a changelog? The changelog is the complete, running record; the release notes are the curated message about one release, written for people who have not decided whether to care. The longer answer is in changelog vs release notes.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.