How to Write Release Notes

This guide leaves you with a release notes format a customer can scan in twenty seconds to answer one question - does this release change anything I need to do - along with a cadence you can sustain and a permanent link for every entry.

Before you start

Decide who the notes are for. Notes for end users and notes for developers consuming an API are different documents with different vocabularies, and merging them produces something neither audience reads.

Agree where the notes live and that the link is permanent. A changelog inside an in-app pop-up that disappears after a week cannot be referenced by support, linked from a ticket, or found by anybody searching for when a behaviour changed.

Only the middle group needs the reader to act. Put it first.

Steps

1. Pick a cadence and hold it.
   Per release, or a weekly digest if you deploy continuously. Irregular notes train readers to stop checking, and the gap is more damaging than the individual entries are valuable.

2. Put required actions at the very top.
   Anything that breaks an integration, changes a default, or needs a customer to do something goes first, with what to do and the date it takes effect. Every other entry can be missed without cost; these cannot.

3. Group the rest into Added, Changed, Fixed and Removed.
   Four predictable headings let a reader skip straight to the one they care about. Readers scanning for a fix should not have to read the new features to find it.

4. Lead each entry with the effect on the reader.
   "Exports now include cancelled subscriptions" rather than "Refactored the export query". The internal work is the cause; the entry describes the consequence.

5. Name features exactly as the interface names them.
   The reader has to map your sentence onto a screen. Internal project names in release notes are the fastest route to an entry nobody can act on.

6. Keep each entry to one or two sentences, with a link for detail.
   The note says what changed; the linked article says how to use it. Notes that grow into documentation become a page nobody scans.

7. Leave internal changes out, with two exceptions.
   Performance improvements a user would notice, and security fixes, are both worth stating plainly. Everything else - refactors, dependency bumps, infrastructure - is noise to the audience you defined.

8. Publish when the change is live for the reader.
   Not when the pull request merged, and not when the deploy finished if the feature is behind a staged rollout. A note describing something a customer cannot see generates support tickets rather than fewer of them.

9. Give every release a permanent, linkable URL with a date and version.
   Support will link it, customers will bookmark it, and a year later somebody will need to know exactly when a behaviour changed.

10. Offer a feed or an email for the people who want it.
    An RSS feed costs nothing to produce and is how technical customers track changes without opening your site.

Common mistakes

Pasting commit messages. Commits are written for the team, use internal nouns, and describe implementation rather than effect. A generated list of pull request titles is not release notes, whatever the tooling calls it.

"Various bug fixes and improvements." This tells a reader nothing while occupying the space where the answer should be, and it is read as a sign nothing worth reporting happened.

Burying a breaking change under new features. The one entry with a deadline attached sits below three paragraphs about a redesign, and the customers who needed it find out when their integration fails.

Writing in the engineering register. Endpoints, migrations, workers and queues describe your system, not the reader's experience of it.

Skipping a release because "nothing user-facing shipped". Say so in one line instead. A gap in the sequence reads as abandonment, and readers cannot distinguish a quiet week from a broken process.

When this stops scaling

Hand-written release notes work while one person can see the whole release. That holds for a single team shipping every week or two, and it stops holding on either of two axes.

The first is team count. Once three or four squads ship independently, no individual knows what went out, and the notes become whatever people remembered to add to a shared document. The entries that get missed are systematically the small behaviour changes, which are exactly the ones support needs later.

The second is continuous deployment. Where changes ship several times a day, "the release" is not a thing anybody can point at, so the notes become an editorial exercise in reconstructing a narrative from a merge log. That reconstruction is the expensive half of the job, and it is the half that gets skipped under pressure.

Both are the same problem: the raw material is in merged pull requests and the finished note is prose about user-visible effects, with a translation step in between. SupportPages drafts that translation from the merged changes and leaves the editorial call to you. Below about a release a week from one team, writing them by hand keeps the judgement where it belongs.