Guide

How to write release notes people read

Most users skip release notes because they read like a commit log. The fix is small, and it starts with writing for the person who uses the product instead of the person who built the change. This guide walks through the steps we use, with before and after examples you can copy.

Start with who reads them

A customer opens your release notes to find out whether anything changed for them. They want to know what they can do now that they couldn't do last week. If something broke for them, they want to see whether you fixed it, and whether they need to change anything on their side. Keep that reader in mind and most of the decisions below get easier.

Lead with the change a user will notice

Put the biggest user-facing change first and give it a plain title. Skip internal names, ticket numbers and the names of libraries you upgraded. If a release only contains refactors and dependency bumps, it may not need public notes at all.

Before
"Refactored export pipeline, migrated to new queue worker (#482)."
After
"CSV exports of large projects now finish in seconds instead of timing out."

Say what it means for them

One or two sentences per change is usually enough. Describe the result from the user's side. If the feature is new, say where to find it in the app, and when a change needs a longer explanation, link to the docs from a one-line note.

Before
"Added SSO support."
After
"You can now sign in with Google Workspace. An admin can turn it on under Settings, then Security."

Group the rest

After the biggest change, list smaller items under simple headings such as New, Improved and Fixed. One line per item is plenty. Readers skim this part, so put the item they are most likely to care about at the top of each group.

Flag anything that breaks

If a change removes a feature, renames something or asks the user to act, put it at the top with a date and the step they need to take. A buried breaking change costs you more support tickets than the rest of the release saves.

Date every entry

Add the release date, and the version number if your users see one. Dates let people match a change to something they noticed, and they show at a glance that the product is still moving.

Write it when you ship

Release notes written a week later lose the detail that makes them useful. Write the entry in the same sitting as the release, while you still remember why the change matters. Users get more from a short entry today than from a polished one that never goes out.

Put them where users will see them

A page people have to go looking for gets few visits. Show new entries inside the app, link the changelog from your footer and your docs, and mention big releases in your email to customers.

Hosting your release notes

ShipLog hosts a public changelog page for your product and adds an in-app widget with a "what's new" badge, which puts each new entry in front of users while they are working inside the app. It's free to start. The free plan holds 10 entries and Captain is $9 a month per project.

Start a free changelog

For a starting point, the release notes templates give you four formats to copy. If you are not sure whether you need a changelog or release notes, read changelog vs release notes before you start.

If your release notes come from GitHub's Generate release notes button, see how to configure GitHub generated release notes for your users.