App versioning: best practices and how to compare releases

App versioning is how you number and track mobile releases: a user-facing version and an always-increasing build number. This guide adapts semantic versioning to apps, lists nine practices, shows which metrics to compare between versions, and walks through a staged rollout where a crash regression was caught at 10% of users.

What is app versioning?

App versioning is the system you use to number and track releases of a mobile app. Every release carries two identifiers: a user-facing version (for example 4.2.1) that people see in the store and in settings, and an internal build number that must increase with every upload. On iOS these are CFBundleShortVersionString and CFBundleVersion; on Android, versionName and versionCode.

Good versioning makes releases predictable for your team, tells users and support which build someone is on, and lets analytics compare behavior, crashes and retention release by release.

Semantic versioning for apps

Most teams adapt Semantic Versioning (SemVer): MAJOR.MINOR.PATCH.

SemVer was written for software libraries, where "breaking" means an incompatible API. For apps, teams usually treat MAJOR as a marketing or redesign milestone rather than a strict rule. Some teams use calendar versioning instead (for example 2026.11.1), which makes the release date obvious.

App versioning best practices

1. Keep the user version and build number separate. The build number must always increase; the user version follows your scheme.
2. Use one version across iOS and Android for the same feature set. It simplifies support and comparisons, even if build numbers differ.
3. Automate build numbers in CI. Use the pipeline run number or a timestamp so they never collide.
4. Tag every release in source control. Tags like v4.3.1 make it easy to find the code behind a crash.
5. Write release notes per version. For users in the store and for your team internally.
6. Report the version with every analytics event and crash. Without it you cannot compare releases.
7. Use staged rollouts. Release to a percentage of users first and watch crash-free users before expanding.
8. Define a minimum supported version. Force or prompt updates when old versions break with server changes, and track how many users are still on them.
9. Keep hotfixes as PATCH releases. So everyone can see a fix shipped without new features.

How to compare app versions

For each new version, compare its first days and weeks with the previous version on:

Compare like with like: users who updated early are often more engaged, so look at new users acquired on each version as well as all users.

Build numbers must increase with every store upload.

Worked example: catching a regression

A food delivery app (sample data) releases version 7.4.0 to 10% of Android users:

Crash-free users fell 1.3 points; error groups showed a new crash on Android 11 in the redesigned address picker. The rollout was paused at 10%, 7.4.1 fixed the crash two days later, and the rollout resumed. Because only 10% of users had 7.4.0, about 90% of potential crashes were avoided.

Common mistakes

• Reusing build numbers. Stores reject them, and crash reports become ambiguous.
• Different version numbers for the same release on iOS and Android. Support and analytics get confusing.
• No version in analytics events. You cannot tell whether a change came from a release.
• Full rollouts on day one. A regression reaches everyone.
• Never retiring old versions. Security and API changes eventually require it.

Tracking app versions in TapCub

• Versions report: App analytics › Users › Versions lists each version with platform, share of active users, crash count and first-seen date, and a stacked chart of the top versions. Click a row to filter the current report to that version. See track app versions.
• Stability: crash-free users, crashes, ANRs, UI freezes and cold start; error groups can be marked resolved.
• Funnels and retention: filter by app version to compare conversion and retention release by release.

Related: crash-free rate, improve app performance, app redesign.

FAQ

What is the difference between version and build number? The version (for example 4.3.1) is what users see. The build number is an internal counter that must increase with every upload to the store.

Should iOS and Android share the same version number? For the same feature set, yes. Build numbers can differ.

When should I increase the major version? When a release is a large redesign or introduces incompatible changes. For apps it is often a product or marketing decision.

How long should I support old app versions? Until usage on them is small and they do not block server or security changes; define a minimum supported version and prompt updates.

Sources

• Preston-Werner, T. Semantic Versioning 2.0.0.
• Android Developers. Version your app.
• Apple Developer. CFBundleShortVersionString.