Release Notes and Changelog Template

Collect everything that shipped since the last release, including changes that went out without a ticket. Then ask one question of each change: if nobody announced it, would a customer notice anything different?

• Yes: something new exists, or something familiar now behaves differently.
• Indirect: internal work with an effect customers can see or measure, such as faster updates.
• No: dependency upgrades, refactors, tests and internal tooling. Leave these out, except security fixes, which belong in the changelog.

Give the indirect changes the most attention. Nobody files a customer-facing ticket for a queue rewrite, yet one that cuts update times from 15 minutes to 90 seconds may be the biggest change in the release.

Don't paste in the commit log, or cover the invisible work with a "various improvements" line. Keep a Changelog, a changelog convention created by Olivier Lacan, says commit logs make bad changelogs because they're full of noise¹, from merge commits to obscure titles.

Rewrite each visible change as one sentence about the reader: what they can do now that they couldn't before. Use the present tense and your customers' words, with no ticket numbers or internal component names. When something is renamed, give both names, since people search for the old one.

A speed or reliability claim needs its before and after. If the work began with a product requirements document, its success metric usually names the number worth quoting.

Give each change a reach figure: how many accounts will notice it, as a count and a share of your customer base. Take it from plan entitlements, feature flag exposure or the number of accounts that use the screen involved. If you can't get a real number, write unknown rather than guessing.

Then sort by it. A feature built for enterprise accounts might reach 3% of customers, while an unglamorous speed fix reaches all of them. Because reach is a number, it settles the running order without anyone having to win an argument.

Make exceptions by hand and keep the figures visible. A change that reaches few accounts but unblocks a renewal earns its own note to that segment, and a cosmetic tweak everyone sees can sit lower.

Pull out every change that requires customers to do something: a removed endpoint, a renamed export column, a changed default. Each one gets its own message, sent before the release and only to the accounts affected, with the deadline in the first line. Inside a release note, it reaches mostly people it doesn't apply to and gets buried for the ones it does.

Match the notice to the work involved. GitHub, for example, supports each version of its REST API for 24 months² after a newer one is released, and promises advance notice of breaking changes. Track who has moved before the deadline, and follow up with each account that hasn't rather than sending another broadcast.

The change still goes in the changelog, with its date in the line, so anyone arriving late learns the deadline. Keep a Changelog is blunt about it: "If you do nothing else, list deprecations, removals, and any breaking changes¹ in your changelog." For an API, update your API documentation in the same release.

Now cut the ranked list for each channel. Every version reuses the same sentences, shortened rather than rewritten, so no two channels describe one change differently.

Name the change in the email's subject line. Nielsen Norman Group's research on newsletter emails found that readers prefer subject lines that describe the content³ over ones that give the newsletter's name or date. It advises putting the key words first and keeping the subject line to 40 characters, so "Tracking now updates within 90 seconds" beats "Release 24.9 is here."

In-app messages work best in context. Nielsen Norman Group's Page Laubheimer classes a list of changes shown at launch as a push revelation⁴: information out of context that interrupts people trying to do something else. Show each item where the feature lives, make it easy to dismiss, and link the full changelog for later.

Mobile apps add a fourth cut: the app store listing. Apple's App Review Guidelines require apps to clearly describe new features and product changes⁵ in their What's New text. Only simple bug fixes, security updates and performance improvements may rely on a generic description. Google Play allows release notes of up to 500 characters per language⁶ and says not to use them for promotion.

The changelog is the complete record: every change a customer could notice, plus security fixes. Keep a Changelog recommends the latest version first and a date on every release¹, with changes grouped as Added, Changed, Deprecated, Removed, Fixed or Security. It also asks you to say whether your version numbers follow Semantic Versioning⁷.

The template at the top of this page works through each step for a sample release. If all you have is a list of commits, turn your commits into a first draft, then run it through the checklist above. If one change deserves a campaign of its own, plan it with the product launch plan template.