How to write release notes people read (with a template)
Good release notes tell users what changed for them, not what changed in the code. This guide covers what to include, how to group changes, where notes are published and their limits, with a template you can copy.
Release notes are the part of a release your users actually see. They are also easy to write last, in a hurry, from a list of merged pull requests, and it shows when they say “Fixed bug in sync service” or “Various improvements”. This guide covers what good release notes include, how to group changes, where they get published and the limits that apply there, with a template you can copy and a worked example.
Release notes, changelogs and why the difference matters
Release notes describe one release for the people who use it: what is new, what changed, what was fixed and whether they need to do anything. A changelog is the running list of every release, newest first. You can publish release notes as changelog entries, so the two overlap; the distinction that matters is the reader.
Keep a Changelog, a published convention for changelog files, starts from the same place: “Changelogs are for humans, not machines.”Source [1] A list of commit messages is a machine’s view of a release. Release notes translate it into what changed for a person.
Who reads release notes
Plan for four readers, in this order:
- Users deciding whether anything affects them. Write so that someone who reads only the headline and the first line of each item still gets the point.
- Admins of business accounts, who need to know about changes they must act on or announce.
- Your support and sales teams, who will be asked about the change before they read about it.
- People who requested the change, who want to know that it was theirs and that it shipped.
If the notes work for the first reader, they work for the rest.
What to include
A useful release note answers five questions:
- What changed? In the user’s words, starting with the benefit: “Notes you edit offline now sync when you reconnect”, not “Implemented offline queue for sync”.
- Who is affected? Everyone, one plan, admins, mobile users?
- Do they need to do anything? A setting to turn on, a migration, a deprecated feature to move off.
- Where do they find it? A short path such as “Settings → Appearance” saves a support ticket.
- Which request did it come from? A link back to the original request shows the people who asked that it was theirs, and closes the loop. More on that in How to close the customer feedback loop.
Group changes by type
Grouping lets readers skip to what matters to them. Keep a Changelog groups entries under fixed headings: Added for new features, Changed for changes in existing functionality, then Deprecated, Removed, Fixed and Security.Source [2] For a product audience, three groups are usually enough:
| Group | Use it for | Example (fictional) |
|---|---|---|
| New | Something users could not do before | Export any notebook to Markdown |
| Improved | Something that works better than before | Search now matches words inside attachments |
| Fixed | Something that did not work and now does | Images in exported notes keep their file names |
Add a Removed or Action needed group only when there is something in it, and put it first: it is the one readers must not miss.
Version numbers
If your product has versions that users or integrations depend on, say how you number them. Semantic Versioning is a published convention for software with an API: a major version for incompatible changes, a minor version when you add functionality in a backward-compatible way, and a patch version for backward-compatible bug fixes.Source [3] For a web app that ships continuously, a date is often clearer than a version number.
Where release notes go, and their limits
The same release can be described in several places, each with its own constraints:
- Your changelog page: the full version, with links and images. This is the one search engines and returning users find.
- Inside the product: a short “What’s new” notice or widget, pointing to the full entry.
- Email: to people who subscribed or asked for the change. One release, one email.
- App stores: Apple’s App Store Connect limits “What’s New in This Version” to 4000 characters,Source [4] and Google Play’s Play Console accepts up to 500 Unicode characters of release notes per languageSource [5] and asks developers not to use release notes for promotional purposes.Source [6] Write the short store version from the full one, not the other way round.
Start from the merged work, then rewrite
If your code lives on GitHub, its automatically generated release notes include a list of merged pull requests, a list of contributors to the release and a link to a full changelog.Source [7] That list is a good checklist of what went into a release. It is not release notes for users: pull request titles are written for reviewers. Use it to make sure nothing is missing, then rewrite each user-facing item in the user’s words and drop the internal ones.
A release notes template
Copy this and fill it in for each release. Delete any section with nothing in it.
# [Benefit-led headline: what users can do now]
[One or two sentences: what changed, for whom, and why it matters.]
## Action needed
- [What admins or users must do, and by when. Remove this section if empty.]
## New
- **[Feature in user words]**: [what it does, where to find it].
You asked for this: [link to request]
## Improved
- **[What works better]**: [the visible difference].
## Fixed
- [What works now that did not before, described from the user's side].
[Version or date] · [Link to the full changelog]A worked example
Here is the template filled in for Driftwood Notes, the fictional note-taking app we use for screenshots:
# Dark mode now follows your system
Driftwood switches between light and dark with your device. You can still pin
one theme in Settings → Appearance.
## New
- **Theme follows your system**: on by default for everyone.
You asked for this: "Dark mode that follows the system setting".
## Fixed
- Notes exported to Markdown keep their image file names.
22 October 2026 · Full changelogNotice what it leaves out: the name of the CSS refactor, the ticket numbers and the word “various”.
Checklist before you publish
- The headline says what users can do now, not what the team did.
- Every item starts with the benefit or the visible change.
- Anything users must act on is at the top.
- Each item that came from a request links to it.
- The store versions fit their limits and are not promotional.
- Someone outside the team can read it without asking a question.
How UpVoiced handles release notes
In UpVoiced, which we are building, release notes are published as changelog entries on your portal. Each entry has a category (New, Improved or Fixed), an optional version and links to the requests it ships, shown on the entry as “You asked, we shipped”. Publishing an entry moves those requests to Shipped and can email the people who followed them, and the changelog has RSS and Atom feeds. The in-app widget shows the same entries in its “What’s new” tab.
If you are choosing a tool for this, our changelog tool checklist lists what to look for. UpVoiced is in development and not open for sign-ups yet; try the fictional demo or request early access.