App release notes: how to write them for users and stores

The short answer

App release notes should say, in plain words, what changed for the user: new features, fixes and anything that behaves differently. Keep them short, specific and honest, and write them separately for each store and language. Skip internal jargon, build numbers and vague lines such as "bug fixes and improvements" when you can say something real.

What app release notes are and where they appear

App release notes are the written summary of an update. They appear in two main places. The first is the store page, in the field Apple calls "What's New" and Google Play calls release notes. The second is inside the app itself, as a changelog screen, an update message or a banner shown after the update installs.

These are different jobs. The store text is read by people deciding whether to update, and by people checking whether the app is still looked after. The in-app message is read by people who already updated and want to know what is different. Treat them as two pieces of writing, even when they share facts.

On Apple's side, the "What's New" text is not available for the first version of an app, but it is needed for every later version, and it can be localised. On Google Play, you add notes per language inside the release screen, using language tags. Both stores set a character limit, and the limits differ, so check the current documentation before you finalise the text.

What should release notes say?

Start with the change a user will notice. Leave out the change only the developers will notice. A useful note answers one question: what can I do now, or what no longer goes wrong?

• New features, described by the task they help with, not by their internal name.
• Fixes, named by the symptom the user saw, such as "Photos no longer fail to upload on a slow connection".
• Changes in behaviour, such as a moved button, a new sign-in step or a changed setting.
• Anything the user must do, such as signing in again or granting a permission.

If an update changes what the app asks for, say so. A new permission request is easier to accept when the notes explain why it exists. The guide on app permissions and privacy basics covers how to decide what to ask for and when.

Do not promise things you have not shipped. Notes that describe a feature that is behind a switch, or only reaching some users, cause confusion. If you roll out in stages, write the notes for what everyone will eventually have, or hold a line back until it is live for all.

How long should release notes be?

As short as the change allows. Most updates need two to five lines. A big release can justify a short list with a one-line headline above it. Anything that needs a page of explanation belongs on a help page or in the app, with the store note pointing to it.

Length also depends on who reads it. Users on a phone see the first few lines and a "more" link. Put the most important change first, because many people never expand the text.

A practical shape that works for most updates:

1. One line saying what is new or better, in the user's words.
2. A short list of fixes, each naming a symptom.
3. One line only if the user has to do something.

If you cannot fill even one honest line, the update may be a maintenance release. It is fine to say that plainly, for example "Under-the-hood changes to keep the app working on the latest system versions". It reads better than a vague claim of improvements.

Writing the what is new text for the app store

The store text sits next to your ratings and screenshots, so it is part of how the app is judged. A page of updates that all read "bug fixes and performance improvements" tells a visitor nothing. It also tells them you did not think the update was worth describing.

Write in the second person and in the present tense: "You can now pause a download", not "Added pause functionality". Avoid ticket numbers, internal code names and technical terms such as "refactored". Keep the tone the same as the app. A playful app can be playful in its notes; a banking-style app should stay plain.

Write each language by hand where you can. A machine translation of a fix description can change the meaning of a symptom. If you only support one language today, plan the release-notes process now so a second language does not mean rewriting every note.

Check the notes against the build before you submit. A mismatch between the text and the app, such as describing a feature that is not in the binary, creates avoidable questions in review and from users. The reasons stores reject apps are covered in why apps get rejected from app stores, though release notes are rarely the main cause.

Do store reviewers read release notes?

Neither Apple nor Google states how closely reviewers read your release notes, so we cannot give a firm answer. What can be said is that the text is part of your submission metadata, and metadata that does not match the app can lead to questions. Write the notes as if someone will compare them with the build.

For the review itself, a separate field is the better place for anything the reviewer needs to know, such as how to sign in to a test account or how to reach a feature that is hard to find. Do not use public release notes for reviewer instructions. They are for users.

Release notes also do not replace changing the version number or the build properly. If you are unsure how updates and versions fit together, read app updates and versioning explained.

Examples: vague notes against useful notes

Notice what the useful versions share. They name something the user can see, they avoid jargon and they say what the benefit is. They are still short. The dark mode line, for example, links to a real design topic, covered in dark mode in apps: design and support basics.

A simple process that keeps notes honest

Release notes are easiest to write when someone collects the facts during the work, not at the end. Keep a running list as changes are merged. At release time, strike out anything the user will not notice and rewrite the rest in plain words.

• Ask the person who tested the fix what the user saw before.
• Have someone outside the team read the draft and say what they think changed.
• Remove any claim that depends on a server setting not yet switched on.
• Keep a copy of the notes with the release, so support can match a complaint to an update.

If your product handles accounts, an update that changes how data is stored or deleted deserves a clear line. The planning side of that is covered in account deletion and user data in apps.

When to get help

Release notes are a writing task, not a technical one, and a founder can usually do them well. The harder part is the release process behind them: versioning, staged releases and store metadata. If you want a team to run that with you, the mobile app development service covers building and shipping apps, and the mobile app development process from idea to launch shows where updates fit in the wider timeline.

Related guides

• Mobile app development
• Mobile app development process from idea to launch
• App Dark Mode: Design and Support Basics for Founders
• App Account Deletion: What Founders Should Plan
• How to write a press release
• App store optimisation basics

Questions and answers

What should app release notes say?

They should say what changed for the user: new features, fixes and any change in behaviour. Name fixes by the symptom people saw. Mention anything the user has to do, such as signing in again.

How long should app release notes be?

Most updates need only a few lines. Put the most important change first, because many people see only the first lines on a phone. If a change needs a long explanation, put it in a help page and point to it.

Do store reviewers read release notes?

Neither Apple nor Google says how closely reviewers read them, so it is safest to assume they may compare the text with the build. Keep the notes accurate, and put reviewer instructions in the field provided for them.

Is it acceptable to write only "bug fixes and improvements"?

The store will not stop you, but it tells users nothing and can look careless on a page where people judge whether the app is looked after. A real line about what changed costs little and reads better.

Do I need different release notes for iPhone and Android?

Usually yes. The fields, limits and language handling differ between the two stores, and the update may not contain the same changes on both platforms. Write each from the actual build.

Should I write release notes in every language?

Write them in each language you support in the store listing. Translating by hand is safer than relying on automatic translation, because a small error can change what a fix description means.