Guide
How to write release notes people read
Updated 2026-11-02 · 5 min read
Short answerGood release notes say what changed, why it matters to the reader, and what to do about it, in plain words and one short entry per change. Lead with the benefit, group changes by type, leave out chores, and link to anything the reader needs to try.
What release notes are for#
Release notes tell the people using your product what changed. They are not a commit log. A commit log answers "what did the developers do?" Release notes answer "what can I do now that I couldn't, and is anything different?"
The five rules#
- Lead with the benefit, not the mechanism. "You can now export a board as CSV" beats "Added CSV export endpoint".
- One change, one line. If a line needs "and", it is probably two changes.
- Use the reader's words. Use the names your interface uses. Never ship an internal ticket title.
- Group by type. Readers scan for what they care about. New, Improved, Fixed and Breaking cover almost everything.
- Leave out the chores. Dependency bumps, refactors and test changes are not release notes. If a refactor makes something faster, say that it is faster.
A template you can copy#
## Dark mode, finally
One sentence on what this release is about and who it is for.
### New
- Dark theme across every screen. It follows your system setting.
- Pin light or dark per device from Settings.
### Improved
- Charts keep their contrast in both themes.
### Fixed
- Exporting a board with an accent in its name no longer fails.
> [!NOTE]
> Anything the reader must do, such as a setting to change or a deadline, goes here.Weak and strong, side by side#
| Weak | Strong |
|---|---|
| Fixed bug in search | Searching for a name with an accent no longer returns nothing |
| Refactored the sync module | Sync is about twice as fast on large workspaces |
| Added webhooks | You can now send an event to your own server when a request changes status |
| Misc improvements | (Say what, or leave it out) |
Breaking changes deserve their own space#
If a change can break something for the reader, say so first and say what to do. A callout at the top, with the date it takes effect and the exact step, saves everyone a support ticket.
Tell the people who asked#
If a feature came from a customer request, tell that customer. "You asked, it shipped" is the most useful sentence in a release note, and it is worth more than any wording trick. See how to close the feedback loop.
Where Shipnoted fits#
Shipnoted can draft release notes from your merged pull requests and leave out the chores, and you edit before publishing. It is a starting point, not a replacement for judgment.
Questions and answers
- What should release notes include?
- What changed, why it matters to the reader, and anything they need to do. Group entries as New, Improved, Fixed and Breaking, and keep each to one short line.
- How long should release notes be?
- As short as the change allows. Most entries are one line; a major feature may deserve a paragraph and a screenshot. If readers have to scroll to find what matters, group and trim.
- What is the difference between release notes and a changelog?
- A changelog is the running, dated list of every release. Release notes are the description of one release. Many products publish release notes as the entries of their changelog.
- Should release notes be written by developers?
- Developers know what changed, but someone should edit for the reader. Drafting from pull requests and then editing in plain words works well.
- Should I list bug fixes?
- List the ones a user would notice or have been waiting for. Leave out internal fixes the reader never saw.