changeloopblog

Release notes practice

How to write release notes people actually read

· changeloop

Bug fixes and performance improvements.

Every product has shipped this. It is not lazy writing exactly. It is what you get when release notes are written from the inside, by someone who has spent two weeks in the diff and can no longer see which parts of it a stranger would care about.

The fix is not a better tone of voice. It is answering one question per entry.

The question

What can the reader do now that they could not do before, and what do they have to do about it?

If an entry cannot answer that, it belongs in the changelog and not in the release notes. Both halves matter. The first half is the value. The second half is the part teams forget, and it is the one that generates support tickets when it is missing.

Two examples of the second half doing real work:

The second one says “no action needed” explicitly. That sentence is worth writing every single time, because a reader who cannot find it assumes the worst.

Order by consequence, not by component

The most common structural mistake is grouping by where the work happened: API, dashboard, mobile, infrastructure. That is your org chart, not the reader’s problem.

Order it like this instead:

  1. Breaking changes and anything with a deadline. First, always, even if it is small. If a reader stops after one line, this is the line they must have read.
  2. What is new that they will want. One per paragraph, with the outcome in the first clause.
  3. What got better. Fixes that were reported, limits that were raised, things that were slow.
  4. Everything else, as a list. Dependency bumps, internal refactors, minor copy. One line each. Nobody reads this section, and it should still be there, because the person looking for it really needs it.

The rewrite

Before:

v4.2.0 Fixed an issue where the POST /exports endpoint would intermittently return 500 under load. Refactored the export worker. Bumped node-pg to 8.11. Improved error handling in the CSV serializer.

After:

Exports no longer fail on large accounts. Accounts over roughly 50,000 rows could get a 500 when starting an export, more often at month end. That is fixed, and exports of any size now retry themselves rather than failing. No action needed, and any export that failed in the last week can simply be run again.

Also in 4.2.0: node-pg 8.11, clearer CSV serializer errors.

Same release. The second one names the account that was affected, the time it was worst, what changed, and what to do. The dependency bump did not disappear, it just stopped being the headline.

Things worth deleting

Cadence beats volume

Notes that arrive for every release train everyone to ignore them. Notes that arrive when something happened get opened. That means it is fine, and usually correct, to ship a release with no notes at all and roll its entries into the next set that has a headline worth reading.

The changelog still records all of it. That is the division of labour: the changelog is complete, the notes are selective. If you keep the changelog structured as you go, writing the notes is selection and rewriting rather than archaeology.

The release notes template is the shape we use for the selection step, and changelog examples collects entries from teams whose changelog is good enough to derive notes from.

One test before you publish

Read the notes as someone who has been on holiday for two weeks and has 40 seconds. If, in that time, they cannot tell whether anything is required of them, the notes are not finished, however accurate they are.

The technical claims in this article have not been independently reviewed. If something here is wrong, tell us and we will correct it.

Related on changeloop: Release notes template, Changelog examples