Release notes template

Last updated 20 August 2026.

Copy the template below, fill in the four sections, delete the ones that do not apply. It is deliberately short: the release notes people actually read are the ones that say what changed and what it means for them, in that order, and stop.

The template

Everything in square brackets is a placeholder. Everything else is worth keeping, including the ordering: users scan for the thing that affects them, so breaking changes go first and internal work does not appear at all.

## [Product] [version] - [date]

[One sentence saying what this release is for. Skip it for routine releases.]

### Breaking changes
- [What broke, what to change, and by when. Link the migration steps.]

### New
- [Capability, described as an outcome. "Pin a filter and reuse it",
  not "added SavedView model".]

### Improved
- [What is faster, clearer or more reliable, and roughly by how much.]

### Fixed
- [The symptom the user saw, not the cause in the code.]

If a section is empty, delete the heading. An empty Fixed section reads as though nothing was fixed, and a heading with nothing under it makes readers think the page failed to load.

The same template, filled in

This is what it looks like with real content. Note that no entry mentions a file, a branch, a ticket number or a person, and the breaking change leads with the action the reader has to take.

## Acme API 4.2 - 20 August 2026

Pagination is now cursor based across every list endpoint.

### Breaking changes
- `?page=` is removed on all list endpoints. Use the `nextCursor`
  value from the previous response. `?page=` returns 400 after
  1 October 2026. Migration steps: acme.example/docs/pagination

### New
- Saved views on the inbox. Pin a filter once and reuse it from
  the sidebar.
- Webhooks can now be scoped to a single project.

### Improved
- List endpoints answer about four times faster on large accounts.
- The export job reports progress instead of appearing to hang.

### Fixed
- Invited members no longer land on an empty dashboard until
  their first sign-in.
- Timestamps in exports now respect the account timezone.

What goes in each section

Breaking changes

The only section with a deadline in it. Say what stops working, what to do instead, and the date it stops. If you have not decided the date, do not publish the section yet: a breaking change without a date gets read as urgent, and a stream of false urgency is how people learn to ignore your release notes.

New

Describe the outcome, not the object you built. The test is whether the line still makes sense to somebody who has never seen your codebase. "Saved views on the inbox" passes. "Added the SavedView model and its migration" does not.

Improved

Quantify where you honestly can. "Faster" is worth almost nothing and readers discount it; "about four times faster on large accounts" is worth reading and sets an expectation you can be held to. If you cannot measure it, say what is better in a way that is falsifiable.

Fixed

Write the symptom, not the cause. Users search these notes for the thing that happened to them, so "invited members landed on an empty dashboard" is findable and "fixed a race in the membership cache" is not.

Variants

The four sections hold for most releases. Three cases want a change:

• Mobile app releases. App stores show a short what-is-new field, so lead with one sentence a person can read in the store listing, then link to the full notes. Store review can also delay a release for days, so date the notes by release date, not by merge date.
• API releases. Version the notes the way you version the API, and put the deprecation window in the notes themselves rather than only in the docs. An API consumer reads the notes precisely to find out how long they have.
• Internal or admin tools. Drop the Improved section and merge it into Fixed. Internal users care about whether their workflow changed, and a long Improved section buries that.

Four rules that keep these readable

1. Write for someone who does not know your codebase. No file names, no branch names, no ticket ids, no service names, no internal codenames.
2. Leave out anything with no user-visible effect. Dependency bumps, refactors, CI changes and typo fixes belong in the commit history, not in release notes. The most common way release notes die is by filling up with work nobody outside the team can see.
3. One entry, one change. If a line needs the word "and" twice it is probably two entries.
4. Publish on a rhythm people can rely on, even if the rhythm is "whenever we ship". Notes that appear four times in a week and then not for two months get treated as noise.

Release notes format: the parts, in order

The format matters less than the order. Whatever heading style you use, a reader scanning release notes wants the same four things in the same sequence, and every popular release notes format is a variation on it.

1. A headline that says what changed for the reader, not the version number. The version goes in a smaller line underneath, with the date in ISO form (2026-08-29) so it reads the same in every locale.
2. Breaking changes and anything with a deadline, first, even when small. If a reader stops after one paragraph, this is the paragraph they needed.
3. What is new, one item per paragraph, with the outcome in the first clause and the action required, including "no action needed", stated every time.
4. Fixes and improvements, then everything else as a one-line list at the bottom. Dependency bumps and internal changes stay, because the one person searching for them really needs them.

In Markdown that is an H2 headline, a muted version and date line, then H3 sections for Breaking, New, Improved and Fixed. In an email it is the same order with the headline as the subject. In a changelog widget it is the headline and the first paragraph, with the rest behind a link. The template above is that shape written out.

For the writing itself rather than the shape, see how to write release notes people actually read and release notes best practices worth keeping on the blog.

Common questions

How long should release notes be?

As long as the changes that affect users, and no longer. A release with one bug fix gets two lines. Padding a small release to make it look substantial trains people to skim past the big ones.

What is the difference between release notes and a changelog?

In practice the terms are used interchangeably. Where teams do distinguish them, release notes describe a single release and are written for users, while a changelog is the running list of every release over time. This template covers one release; a changelog is what you get when you stack them newest first.

Should release notes have a version number?

Only if your users can see it. Version numbers are useful for APIs, libraries and installed software, where a reader needs to know which version they are on. For a continuously deployed web app the date is more useful, because that is what the user can match against what they experienced.

Who should write them?

Whoever knows what changed, which usually means the engineer who merged it, edited by whoever owns the voice. The failure mode of handing them entirely to someone outside the work is notes that describe the ticket instead of the change.