Two jobs, two audiences
Versioning is mainly for you and the store: it identifies exactly which build is which. Release notes are for people: they explain what changed. Doing both well takes a little discipline and saves time later, because you will be asked which version fixed a given problem, and users will wonder whether to update.
A simple numbering scheme
Many apps use three numbers separated by dots, such as 2.4.1. A common convention, often called semantic versioning, reads them as major, minor and patch:
- Major (the first number) changes when there is a big shift, such as a redesign or a change that alters how people use the app.
- Minor (the second) increases when new features arrive.
- Patch (the third) increases for bug fixes and small corrections.
So going from 2.4.1 to 2.4.2 suggests a small fix, 2.5.0 suggests new functionality, and 3.0.0 suggests something larger. The convention is a guide, not a law, and consumer apps do not always follow it strictly. What matters is that you pick a scheme and apply it consistently.
The two numbers the stores track
Both major platforms distinguish between the version shown to people and an internal build number. The visible version might be 2.4.1, while the build number is a simple counter that goes up with every upload. The build number generally has to increase each time you submit, even if the visible version does not change. The exact names and rules differ between platforms, so check the documentation. A tidy approach is to let your build tools increment the internal number automatically, so you never forget.
Tag what you ship
Using version control, mark the exact commit for each release with a tag matching the version. When a user reports a problem in version 2.4.1, you can check out precisely that code. This habit costs seconds and is very useful when something goes wrong.
What good release notes do
Many users never read release notes. Those who do are often wondering a specific thing: did the problem I reported get fixed, is there something new, and will anything change for me? Notes that answer those questions are worth writing.
Be specific. “Bug fixes and performance improvements” tells nobody anything, even if it is occasionally accurate. “Fixed a problem where the reminder screen could close unexpectedly after saving” is better, provided it is true.
Lead with what matters to users. Put the most noticeable change first. Group the rest briefly.
Use plain language. Avoid internal ticket numbers and jargon. Write as you would explain it to a friend.
Keep it short. A handful of lines is plenty. Some stores limit the length, so check.
Be honest about problems. If something is temporarily removed or a known issue remains, say so. People tend to forgive honest notes more readily than silent surprises.
A simple structure
A pattern that works for small apps:
- New: features added
- Improved: things that now work better
- Fixed: problems resolved
- Heads-up: anything people should know, such as a changed setting or a dropped older phone version
Leave out any heading with nothing under it.
Mention changes that affect trust
Some changes deserve a clear note, not a buried line:
- New permission requests or new kinds of data collection
- Changes to subscriptions, pricing or what is free
- Removal of features
- A change in the minimum supported version of the operating system
If an update asks for a new permission, people should not be left to find out from a system prompt. Telling them why, in the notes and in the app, respects them and tends to prevent angry reviews. This ties in with good practice on mobile app privacy.
Write notes that thank, but don’t gush
If a fix came from user feedback, a short thanks is welcome, such as “Thanks to everyone who reported this.” Avoid exaggeration. Claims like “the best update ever” age badly and read as marketing.
Where else notes appear
You may need slightly different versions in several places: the store’s “what’s new” field, an in-app message for major changes, and perhaps a page on your own site. A longer changelog on your website can hold the full history for anyone interested, while the store text stays brief. Consistency matters, so keep one source of truth and trim it for each place.
Connect notes to your routine
Keep a running list of changes as you work, adding a line whenever you fix or add something. At release time, the notes nearly write themselves. Without that habit, people tend to reconstruct changes from memory and forget half of them. This pairs with careful handling of app updates and with a feedback routine that lets you tell people what has been fixed.
Do not hide behind version numbers
Jumping from 1.9 to 5.0 to make an app seem more mature, or constantly releasing “major” versions to look busy, does not fool anyone for long. Numbers should tell the truth about what changed.