Release notes template
Six release notes templates you can copy and fill in, for desktop apps, changelogs, app stores, hotfixes and customer emails, plus the handful of rules that make release notes worth reading.
Release notes tell the people who use your software what changed in a new version, in words they understand. A good template gives every release the same shape: the version and date, what's new, what's better, what's fixed, and anything the reader has to do.
Below are six templates in plain text and Markdown. Copy the one that matches where your notes will be read, replace the bracketed parts, and delete the sections you don't need. An empty "Fixed" heading is worse than no heading.
1. The standard release notes template
This one works for most products. It's what to use if you publish notes on a website, a GitHub release or a help centre.
# [Product name] [version]
Released [Month D, YYYY]
[One or two sentences on the main thing in this release and why it matters.]
## New
- **[Feature name].** [What you can do now that you couldn't before.]
- **[Feature name].** [What it does, and where to find it.]
## Improved
- [Thing that got faster, simpler or clearer, with a number if you have one.]
- [Another improvement.]
## Fixed
- [The problem as the user saw it, not as the code described it.]
- [Another fix.]
## Before you update
- [Anything the reader must do, or anything that will behave differently.]
Filled in, it looks like this:
# Inkwell 3.2
Released November 17, 2026
You can now export a whole notebook as one PDF, which was the most
requested feature this year.
## New
- **Export a notebook to PDF.** Choose File, Export, Notebook as PDF.
Page breaks follow your section headings.
- **Dark mode for the editor.** Follows your system setting, or set it
in Settings, Appearance.
## Improved
- Search is about twice as fast in notebooks with more than 1,000 notes.
- The sidebar remembers its width between launches.
## Fixed
- Pasting from Word no longer adds blank lines between paragraphs.
- Fixed a crash when opening a note with a very large image.
## Before you update
- Inkwell 3.2 needs macOS 13 or later. On older versions of macOS,
Inkwell 3.1 keeps working and keeps syncing.
2. Desktop app update template (the in-app update dialog)
When a desktop app finds an update, the updater shows your release notes in a small window with an "Install" button under it. The reader is deciding one thing: update now, or later. So this template is short, has no top-level title (the dialog already shows the app name and version), and leads with the reason to update.
[One sentence: the best reason to install this update.]
**New**
- [Feature, in a few words.]
- [Feature, in a few words.]
**Fixed**
- [Fix, as the user experienced the problem.]
- [Fix.]
[Optional: one line on anything that changes after updating.]
Two things to know about this format:
- Keep the formatting simple. Update dialogs render notes as basic HTML or as plain text, depending on the updater. Bold, lists and links are safe. Images, tables and custom styling often aren't.
- Look at what your pipeline is sending. If your release workflow forwards the body of a GitHub release, GitHub's auto-generated "What's Changed" section, with your pull request titles and repository links, can end up inside your customers' update dialog. Write the customer-facing notes by hand and cut the generated part before publishing.
If you ship updates through LicenseSeat, each release has a curated notes field that every update feed prefers over what your CI posted, so you can fix the wording of a live release without shipping a new build. The guide to shipping desktop updates covers it.
3. Changelog template (Keep a Changelog format)
A changelog is the complete, cumulative record of every version in one file, usually CHANGELOG.md at the root of the repository. The most widely used convention is Keep a Changelog, which groups changes under six fixed headings.
# Changelog
All notable changes to this project are documented in this file.
This project follows Semantic Versioning.
## [Unreleased]
### Added
- [Change that's merged but not released yet.]
## [1.4.0] - 2026-11-17
### Added
- [New feature.]
### Changed
- [Change to something that already existed.]
### Deprecated
- [Feature that still works but will be removed.]
### Removed
- [Feature that's gone in this version.]
### Fixed
- [Bug fix.]
### Security
- [Vulnerability that was fixed.]
## [1.3.2] - 2026-10-02
### Fixed
- [Bug fix.]
The conventions that matter: the latest version goes first, every version has its release date in YYYY-MM-DD form, and an "Unreleased" section at the top collects changes as they're merged, so writing the next release's notes is mostly moving that section down.
4. App Store and Google Play template
Store release notes ("What's New" on the App Store, "What's new" on Google Play) are plain text with no formatting, and they have length limits. Apple allows 4,000 characters for "What's New in This Version". Google Play allows 500 characters per language, which is about four short lines.
[One sentence on the headline change.]
NEW
• [Feature, in a few words]
• [Feature, in a few words]
FIXED
• [Fix]
• [Fix]
[Optional: Thanks for the feedback, keep it coming at [email protected]]
Write the Google Play version first. If it fits in 500 characters it'll fit anywhere, and the limit forces you to pick what matters.
5. Hotfix or patch release template
A patch release fixes something that's broken. People reading it want to know three things: am I affected, is it fixed, and do I have to do anything.
# [Product name] [version]
Released [Month D, YYYY]
This update fixes [the problem, as users experienced it], which
affected [who: everyone / people on Windows 11 / anyone using feature X]
since version [version].
## Fixed
- [The main fix.]
- [Any smaller fixes that came along.]
## What you need to do
[Nothing, just update. / Update, then do X once.]
[If data was affected: what happened to it and how to recover it.]
If the bug was your fault and it cost people time, say so in one plain sentence. It reads better than pretending the previous version never happened.
6. Release announcement email template
For a bigger release you'll want to tell customers who haven't opened the app lately. An email isn't the full notes: it's the three things most worth knowing, and a link.
Subject: [Product name] [version]: [the headline feature in five words]
Hi [first name],
[Product name] [version] is out. Here's what's in it:
1. [Headline feature]. [One sentence on what it lets you do.]
2. [Second feature]. [One sentence.]
3. [Third thing, or the most-wanted fix]. [One sentence.]
[How to get it: "The app will offer the update next time you open it",
or a download link.]
The full release notes are here: [link]
[Your name]
How to write release notes people read
Write for the person using the app. "Fixed a null pointer in the sync queue" is a commit message. "Fixed a crash when syncing with no internet connection" is a release note. Describe what the user saw.
Lead with the reason to update. Most people read the first line and nothing else. Put the best thing there.
Group by kind of change. New, improved, fixed. Readers scan for the part they care about, and someone waiting on a fix goes straight to "Fixed".
Be specific. "Performance improvements" tells nobody anything. "Projects with over 500 files open about three times faster" does.
Say what breaks. If the update changes a default, drops support for an old operating system or needs the user to do something, give it its own heading. That's the one part of the notes that prevents support email.
Skip what users can't see. Refactors, dependency bumps and test changes belong in the commit history. If a release is only internal work, one honest line is fine: "Behind-the-scenes improvements to stability."
Don't ship generated notes unedited. A list of merged pull requests is a starting point for writing release notes. It isn't the release notes.
Keep the same shape every time. The point of a template is that readers learn where things are.
Release notes vs changelog
They overlap, and plenty of projects use the words interchangeably, but they're written for different readers.
| Release notes | Changelog | |
|---|---|---|
| Written for | Users and customers | Developers and maintainers |
| Covers | One release | Every release, in one file |
| Includes | What matters to the user | Every notable change |
| Tone | Plain language, benefits first | Terse and technical |
| Lives | Update dialog, website, store listing, email | CHANGELOG.md in the repository |
A small project can get by with one document doing both jobs. Once you have non-technical customers, keep the changelog complete and write the release notes from it.
A release checklist for desktop apps
Release notes are one step in getting a new version to customers. If you sell a desktop app directly, the rest of the release usually looks like this:
- Bump the version number
- Build and sign the app: SignTool on Windows, Developer ID and notarization on macOS (which is what keeps your users away from
xattr -cr) - Package it, as a DMG or a PKG on macOS or an installer on Windows
- Write the release notes
- Publish the build and the notes to your update feed
- Open the previous version and check that the update dialog shows what you meant it to
LicenseSeat covers steps 5 and 6 along with the licensing: it hosts your builds, serves the update feed to licensed customers, and shows your release notes in the update dialog. It charges a flat monthly fee and takes 0% of your revenue. If you're setting all of this up for the first time, start with the guide on how to sell software online.
Common questions about release notes
What should release notes include?
The version number and release date, a one-line summary, the new features, the improvements, the bug fixes, and anything the reader must do or that will work differently after updating. Leave out any section that would be empty.
How long should release notes be?
As short as they can be while still being specific. A typical release fits on one screen. In an in-app update dialog aim for under ten lines, and on Google Play you're limited to 500 characters.
What is the difference between release notes and a changelog?
Release notes describe one release for the people who use the product, in plain language. A changelog is a complete, running list of changes across every version, usually kept in a CHANGELOG.md file for developers.
What format should release notes be in?
Markdown is the safest choice. It reads fine as plain text, GitHub and most documentation tools render it, and it converts cleanly to HTML for a website or an update dialog. App stores take plain text only.
Should I list every bug fix?
List the ones a user could have noticed. A fix for a crash people reported belongs in the notes. A fix for a bug nobody hit, in a feature that wasn't released yet, doesn't.
Who writes release notes?
Whoever is closest to the customer and understands the change: often a product manager, a technical writer, or on a small team the developer. Whoever it is, the draft usually starts from the list of merged changes and gets rewritten in the user's terms.
Can I generate release notes automatically?
You can generate a first draft from commit messages or pull request titles, and it saves time. Edit it before customers see it, since generated notes describe code changes, not what changed for the user.