Release Notes Best Practices for SaaS Teams

Good release notes answer one question: what changed for me? Everything else is optional.

Most release notes fail because they answer a different question, which is what changed in the codebase. "Various bug fixes and performance improvements" is the extreme version, but "Refactored the sync engine" is the same mistake with more detail.

This is the reference we use ourselves. It covers the writing, the mechanics of the App Store and Google Play fields, and the parts of the process that decide whether the notes get written at all.

Start with the reader, not the release

Before writing anything, decide who the notes are for. Three audiences read release notes, and they want different things.

One set of notes can serve all three, but only if it is written for the first. Notes written for the third read like a ticket export, and the first audience stops opening them.

Lead with the change, not the feature name

The most common structural mistake is naming the thing before saying what it does.

Introducing Smart Groups.

That sentence is only useful to someone who already knows what a Smart Group is, which is nobody, because it shipped ten minutes ago.

You can now filter a list once and save it, so you do not rebuild the same filter every morning. We call it Smart Groups.

The second version costs twenty-two more words and works for a reader who has never heard the name. Name the feature after you have earned the reader's attention, not before.

Write in the order the reader cares about

Order matters more than length, because most readers stop after the first item.

1. Changes to something they already use.
2. New capability they can use today.
3. Fixes for problems they reported.
4. Everything else.

A fix for a crash on the screen half your users open first belongs above a new integration nobody has asked for yet. Shipping order and reading order are rarely the same.

Say what a fix actually fixed

"Fixed a bug" is not a release note. It gives a reader no way to tell whether the bug was theirs.

Compare:

Fixed a bug with exports.

Exporting a report with more than 1,000 rows produced an empty file. It no longer does.

The second version lets someone who hit that problem stop working around it. It also lets everyone else skip the line in half a second, which is a feature.

Keep the vocabulary you use in the product

If the button says Workspace, the note says Workspace. If the note says Organization, the reader goes looking for a screen that does not exist.

This sounds obvious until a release includes a rename. When something changes name, say both:

Workspaces are now called Projects. Nothing else about them changed.

Know the field you are writing into

Release notes are constrained by the surface they ship to, and the two mobile stores are not the same.

The third row is the one that catches people. Apple hangs What to Test on the build rather than the version, so it does not carry forward: every upload starts with an empty note, and a tester who installs build 24 after reading build 23's notes sees nothing unless you write them again.

The 500 character limit on Google Play is the constraint that shapes everything. If you write for the App Store first and then paste into Play, you will be cutting under pressure, and the cut usually removes the specifics that made the notes worth reading.

Write the Play version first. Three sentences that fit in 500 characters translate cleanly into every language you ship in and expand easily for the App Store. Going the other way does not work, because a translation is usually longer than its English source, and German in particular runs long enough to push a note that just fit over the limit.

Apple also rejects emoji in listing text, so a note that reads well with a rocket in it on your web changelog has to be written twice anyway.

Version numbers are not release notes

A note that says "Version 4.2" tells the reader nothing they cannot see above it. Neither does a date.

Both are worth including as structure, never as content. The store already prints the version number and the release date; your 500 characters should not repeat them.

Decide what counts as worth mentioning

Not every release has a story. A useful rule: mention a change if a reasonable user could notice it, or if they asked for it.

That includes:

• Anything that changes what a screen looks like or where a control lives.
• Anything that changes what an existing action does.
• Fixes for problems that were reported by users, even small ones.
• Performance changes big enough to feel.

It excludes:

• Dependency upgrades that changed nothing observable.
• Internal refactors.
• Infrastructure work, unless it changed a limit or a price.

When a release genuinely contains none of the first list, say so plainly:

This release is maintenance only: dependency updates and internal cleanup. Nothing you use has changed.

That is a better note than an invented feature, and readers reward it. It also gives you a reason not to invent one.

Write the notes before the release, not after

The single change that improves release notes most is writing them earlier.

Notes written after the build is uploaded are written by whoever is doing the upload, usually at the end of a long day, from a list of merged pull requests. Notes written when the work is merged are written by the person who did it, while they still remember why it mattered.

Two workable versions of this:

• A changelog entry in the pull request. A short user-facing line in the PR description or a changelog: label. The release note is assembled from those lines.
• A running draft. One document per upcoming version that anyone can add to. At release time it gets edited down rather than written.

Either beats reconstructing the release from Git history, which is how "various improvements" gets written.

Translate deliberately, not automatically

If you ship in more than one language, the notes have to ship in those languages too, and an untranslated What's New field falls back to your default language on a listing that is otherwise fully localized. That looks like neglect, because it is.

Two things worth doing:

• Translate from the shortest version, not the longest, for the character limit reason above.
• Read the translation against the limit before you save it, not after the store rejects it.

Machine translation is fine for release notes in a way it is not for marketing copy, as long as the source sentence is simple. Short declarative sentences translate well; a joke does not.

A template that holds up

For Google Play, inside 500 characters:

What's new in 4.2
 
- Filter a list once and keep it. We call them saved filters.
- Exports over 1,000 rows no longer come out empty.
- Faster launch on Android 12 and older.

For the App Store, the same content with room to breathe:

Filter a list once and keep it
Save a filter so you do not rebuild the same view every morning. We call them
saved filters, and they sit at the top of any list.
 
Fixes
- Exporting a report with more than 1,000 rows produced an empty file.
- The app took several seconds to open on an iPhone SE. It no longer does.

Both are scannable, both lead with the change and name the feature after it, and both would survive translation.

What to measure

Release notes are worth measuring for two things, and neither is a vanity metric:

• Support volume after a release. If a change generates tickets asking "where did X go", the note about it was missing or unclear.
• Adoption of the thing you announced. If a feature ships and nobody uses it, the announcement is the cheapest part of the funnel to fix.

Read counts and reactions are useful for an in-app changelog, where you control the surface. On the App Store and Google Play you get neither, which is a good reason to keep the notes short and the claims honest.

The short version

• Say what changed for the reader, first sentence.
• Name the feature after you have explained it.
• Write the fix so somebody can tell if it was theirs.
• Write the 500 character version first, then expand.
• Write notes when the work merges, not when the build uploads.
• Say "maintenance only" when it is true.

If you want the tools side of this, we compared the changelog tools teams actually use, including the free ones.