Release notes best practices worth keeping
Search for release notes best practices and you get style advice: be clear, be concise, use plain language, add screenshots. None of it is wrong and none of it changes anything, because no team has ever sat down intending to be unclear.
The practices below are the ones with a consequence. Each is followed by what it costs you if you skip it, because a practice without a failure mode attached is just a preference.
Practices that earn their place
Write the entry when you merge, not when you release. Cost of skipping: the person reconstructing the release from commit history is not the person who made the change, and they will guess at intent. Entries written a fortnight later are the ones that say “various improvements”.
Say who is affected, by name. “Teams on the Business plan”, “anyone using the v1 export API”, “self-hosted installs on Postgres 14”. Cost of skipping: every reader has to work out whether it applies to them, and most will decide it does not.
State the required action, including when it is none. Cost of skipping: support answers the same question forty times, and the readers who did not ask just assume something is required and put it off.
Give breaking changes a date, not a release number. “Removed in v5” means nothing to someone who does not know when v5 lands. “Stops working on 1 November” is a date they can put in a calendar. Cost of skipping: the deadline is discovered after it passes.
Keep one permanent, linkable entry per change. An email is not an archive and a Slack message is not a reference. Cost of skipping: nobody can answer “when did this change” six months later, including you.
Group by outcome, not by system. Cost of skipping: the reader has to hold your architecture in their head to work out which section matters to them.
Keep the boring section. Dependency bumps and internal changes stay, at the bottom, in one line each. Cost of skipping: the security team, the compliance reviewer and the person debugging a version mismatch all lose their only source.
Changelog best practices, which are not the same thing
A changelog is a reference, so its practices are about completeness and structure rather than persuasion:
- A fixed entry type per line. Added, Changed, Deprecated, Removed, Fixed, Security. Not a house style, a filter: it is what lets someone ask for “just the breaking changes”.
- An unreleased section. Where entries live between merge and release. Its absence is why teams write entries late.
- ISO dates.
2026-08-28, not28/08/26, which means two different days depending on the reader. - One entry per change, not per commit. Three commits fixing one bug are one entry.
Three that are cargo cult
Emoji as entry types. A rocket and a wrench are not a taxonomy. They look tidy and they cannot be filtered, sorted, or read by a screen reader in any useful way. Use words, and if you want the emoji, put them after the word.
Semantic version numbers as headlines for a hosted product. Semver is a promise about API compatibility. For a SaaS product where nobody chooses their version, a version number in the headline is internal filing dressed up as news. Keep semver in the changelog and out of the announcement.
Publishing on a schedule regardless of content. Monthly notes with nothing in them teach people that your notes are noise. Publish when there is something to say. The changelog covers the rest.
The one that is actually hard
Keeping the changelog and the announcement in step, without writing everything twice.
Most teams start with one page, split it when the audiences diverge, and then quietly let one of the two rot, usually the changelog, because it is the one with no deadline attached. The way out is structural rather than disciplinary: keep the entries as data with a type, a date and an audience, and treat both surfaces as renderings of that. Our changelog tools roundup covers what is available for that, including the tools we compete with.
The release notes template is where the selection step lives once the entries exist.
If you adopt one thing
Write the entry at merge time, in a fixed format, with a type. Every other practice on this page gets easier once that one is in place, and none of them survive without it.
The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.