Lorixen.
EN

Version Numbers, Build Numbers and Release Notes: A Release Checklist for Your App

Short answer: Every app update carries two numbers. The version is the human-friendly label such as 2.3.0, shown in the store and used in conversation. The build is an internal counter that must rise with every file you upload, even when the version stays the same. Mix them up and the store rejects your upload, or support cannot tell which release a customer is running. Decide the rules once, write them down, and run the same checklist every time.

Two numbers, two jobs

On iPhone

Apple uses a short version string, the one customers see, and a build number. A version can have many builds. If build 12 of version 2.3.0 has a bug found before release, you upload build 13 with the same version. App Store Connect expects each build number to be unique within a version, and in practice it is simplest to let the build number only ever go up.

On Android

Android calls them version name and version code. The name is text, shown to people. The code is a whole number that must increase with every release uploaded to Google Play, and the store compares codes to decide which build is newer. Google documents an upper limit on that number, so a clean counter such as 1, 2, 3 is safer than clever date-based encodings that grow quickly.

Check the current limits and naming on the official versioning pages, as those details can change.

The practical rule

Keep one shared build counter across both platforms if you can. Then "build 87" means the same commit of the code on iPhone and Android, which helps support and testing. Some teams prefer separate counters. Either works if it is written down.

What a sensible version scheme looks like

A common pattern is three parts: major.minor.patch.

  • Patch (2.3.1): bug fixes only. No visible new features.
  • Minor (2.4.0): new features that do not break anything.
  • Major (3.0.0): a big redesign, or a change that affects how people use the app.

You do not need to follow it rigidly. What matters is that you and your developer agree. A bakery ordering app might go 1.0.0 at launch, 1.1.0 when pre-orders arrive, 1.1.1 for a fix to the pickup time picker.

Avoid labels that change meaning, such as "Spring release". Customers and support staff need something they can read from Settings and quote in an email.

Writing release notes people read

Both stores show a short text with each update: App Store calls it What's New, Google Play calls it release notes. Google limits the length of the text per language, so keep it brief. Apple allows more room, but nobody reads a wall of text.

Good notes are specific and honest:

  • Say what changed for the customer. "You can now reorder your last basket in one tap" beats "Performance improvements".
  • Mention fixes that people noticed. "Fixed: pickup times showed in the wrong time zone for Ireland" tells affected users you listened.
  • Skip the internal detail. Nobody needs to hear about a library upgrade.
  • Keep the voice of your business, not a stock phrase. Repeating the same line every release trains people to ignore the field.

Illustrative example for a fictional dog-walking app, version 2.1.0: "New: share a walk's route map with the dog's owner. Fixed: walks started after midnight were filed under the wrong day. Smaller text fits better on older phones."

If you serve several countries, ask whether notes need translating. Both stores allow notes per language.

The release checklist

Run it in order before pressing the submit button.

Before the build

  • [ ] Agree what is in this release and what is not
  • [ ] Update the version number according to your scheme
  • [ ] Raise the build number above the last uploaded one
  • [ ] Check that settings pointing to testing servers have been switched to live ones
  • [ ] Confirm app permissions have not been added without a reason, since new ones can trigger extra review questions

Testing

  • [ ] Install the release build, not a developer build, on at least two real devices per platform
  • [ ] Test an upgrade from the previous live version, not only a fresh install
  • [ ] Walk through the five tasks your customers do most
  • [ ] Test sign-in, payment in test mode, and account deletion if you offer it
  • [ ] Check the demo account for store reviewers still works

Store fields

  • [ ] Write release notes in each language you support
  • [ ] Update screenshots only if the screens have changed noticeably
  • [ ] Review privacy information if you now collect something new
  • [ ] Choose a release method: automatic on approval, manual release, or a staged rollout
  • [ ] Set a minimum supported OS version only if you meant to change it

After approval

  • [ ] Watch crash reports and reviews for 48 hours
  • [ ] Note the version and build in a simple release log
  • [ ] Tell staff and key customers what changed, if it matters to them
  • [ ] Keep the source code tagged with the version so you can find it later

Mistakes we see most often

Reusing a build number. The store refuses the upload, and the person scrambling to release on a Friday loses an hour.

Different version labels per platform without a reason. Customers on iPhone get 3.0, customers on Android get 2.9, and support has to translate. Keep labels matching unless a platform-specific fix forces a difference.

No record of what shipped. Six months later nobody knows which build contained which change. A shared spreadsheet with date, version, build, summary and who approved is enough.

Forgetting the web and server side. An app update may need a matching server change. Note any dependency in the release log, such as "needs API change deployed first".

Publishing notes written in a rush. "Bug fixes" repeated ten times says you do not care. A one-line real change is better.

Keeping a release log

Four columns are enough:

Date Version (build) What changed Notes
2026-03-04 1.2.0 (41) Pre-order button Needs server v8
2026-03-18 1.2.1 (44) Fix pickup time Hotfix

Dates and names here are invented examples. Your own log gives you a quick answer when a customer says "it broke last week".

FAQ

Can the version stay the same for two uploads?

On iPhone, yes, if the build number rises. On Android, the version name can repeat, but the version code must increase every time.

Should version numbers match our website's?

Not necessarily. They describe different things. Keep the app's own scheme.

Do we have to write release notes for tiny fixes?

Yes, but a short, real sentence is enough. The field is part of how customers judge whether you are looking after the app.

Who should own the log?

One named person, ideally the one who approves releases.

If your updates feel chaotic, send us your current release steps and we will turn them into a routine your team can repeat.

Sources

WhatsAppBook a call