App Versioning: Schemes, Examples and Best Practices
App versioning is the practice of giving every release of an app a unique identifier. It lets you trace what a release contains, when it shipped and even where it runs.
Overview & context
"Which version of the app are you on?" "Well, the latest one..." — an answer that leaves you knowing exactly as much as before. Let's go through the different approaches to versioning, explain the difference between a version and a build number and show the places where the version should be visible. Maybe then you'll avoid answers like that.
1. What app versioning is and why it matters
A version number is a shared label for development, support and the customer. When a customer deals with a problem or asks for a new feature, they start from the version of the app they have installed. For developers and support, it's key information.
Without versions, you can go by the install date, dig through the CI/CD deployment history or search tasks in your ticketing system. That's neither reliable nor quick.
2. Versioning schemes: semantic versioning (SemVer), CalVer and sequential numbers
Semantic Versioning (SemVer) uses three numbers, MAJOR.MINOR.PATCH. Each part describes the nature of the change, so the number alone tells you how big the change is.
| Scheme | Format | Best for |
|---|---|---|
| SemVer | MAJOR.MINOR.PATCH, e.g. 2.4.1 | Libraries, public APIs, anything used by third parties that requires backward compatibility |
| CalVer | YYYY.MM(.sequence), e.g. 2026.10.2 | Regularly released apps where the age of a release matters |
| Sequential | Incrementing integer, e.g. 482 | Internal tools, automated builds |
3. Calendar versioning (CalVer) and sequential version numbers
Calendar Versioning (CalVer) encodes the release date into the version, for example 2026.10 or 26.10.2. It suits apps with a regular release cadence, where users care less about compatibility and more about how current the app is. Users can tell from the number alone that version 25.01.1 came out back in early 2025.
The simplest option is a sequential number that goes up by one with every release. It's enough for automated builds and internal tools, but a human can't read the release date or a breaking change from it. That's why it's usually combined with one of the schemes above.
4. App versioning examples: how the version number changes
The same version history looks different in each scheme. The table shows how the version number changes in each of them.
You'll often see various suffixes added to SemVer's three numbers. For example, pre-releases use a hyphen (2.0.0-beta.1, 2.0.0-rc.1) and have lower precedence than the final 2.0.0. Build metadata, written after a plus sign (2.4.1+482), carries extra information but doesn't affect version precedence.
| Release | SemVer | CalVer (YY.MM.sequence) |
|---|---|---|
| First public version | 1.0.0 | 26.08.0 |
| Bug fix | 1.0.1 | 26.08.1 |
| New feature | 1.1.0 | 26.09.0 |
| Another fix in the same month | 1.1.1 | 26.09.1 |
| Breaking API change | 2.0.0 | 26.10.0 |
5. Version number vs. build number in mobile apps (Android and iOS)
Mobile platforms distinguish two values. The version is the text users see in the app store. The build number is a technical value the store uses to tell that an uploaded package is newer than the previous one.
On Android these are versionName (any text, e.g. 2.4.1) and versionCode (a positive integer that must increase with every upload to Google Play). On iOS they are CFBundleShortVersionString (a version of three period-separated integers) and CFBundleVersion (the build number, exposed in Xcode as MARKETING_VERSION and CURRENT_PROJECT_VERSION).
A user reports version 2.4.1, but it may have shipped in three builds. If support only sees the version, they can't tell which build the user actually has. If you don't change the version together with the build number every time, the build number belongs next to the version on the "About" screen and in system logs too.
| Platform | Human-readable version | Build number |
|---|---|---|
| Android | versionName = "2.4.1" | versionCode = 482 |
| iOS | CFBundleShortVersionString = 2.4.1 | CFBundleVersion = 482 |
| Flutter (pubspec.yaml) | version: 2.4.1+482 (part before +) | part after + |
| Expo (app.json) | version | android.versionCode, ios.buildNumber |
6. Where the app version should be visible
A version number hidden in the source code usually helps no one. Include the version wherever you need to tell how old the app is, most often in system and transaction logs, API calls, interface definitions and configurations. Show the version number in the user interface too: in the app's settings, in the website footer or on an about screen. Keep in mind that a consultant, a tester and a regular user all need to be able to find the version easily.
In AboutTheApp, the About box plays this role. You add it to the app once and it shows the current version right in production. If you pass your build's version in its version attribute, it shows exactly the version that's running, even when nobody recorded the new release in AboutTheApp. The About box links to the public About page with the app's version history and a list of changes.
Along with the version, keep a changelog: a list of changes available to the app's users, with release notes for each version. The Product Versions tab on AboutTheApp's own About page shows what such an overview looks like.
7. Tracking app versions across customers
Once an app runs for several customers or in several environments, knowing the single latest version usually isn't enough. A given customer will have one version in production and another on staging and other customers may have versions of various ages installed. Ideally, of course, you'll try to keep every customer on the newest version possible, because maintaining outdated installations is demanding and risky. In practice, though, this situation is common, especially during the transition period after a new release.
In AboutTheApp, each product keeps a version catalog with changelogs and each customer and environment gets deployments with a specific version, URL and location. The dashboard then shows deployments per customer on each product and flags outdated installations, so you can see at a glance who is running an old version.
You can record versions and deployments manually in the dashboard, but it's better to sync them straight from your repository's CI/CD. The customer then sees the state of their environments, including the deployment history, in the Environments & Versions tab of their About page.
Every version has its own visibility: it can be public or private. Private versions are visible only to you or to a verified user; public ones show up for everyone.
8. App versioning best practices
No scheme is universally the best. What matters more than the choice of scheme is that the whole team follows the same versioning convention and doesn't change it during the app's lifecycle.
Frequently asked questions
What does an app version number mean?
An app version number identifies one specific release of the app. In SemVer, for example 2.4.1, the first number marks breaking changes, the second new backward-compatible features and the third bug fixes. In CalVer, the number tells you when the release came out, for example 26.10 for October 2026.
What's the difference between a version number and a build number?
The version number is meant for people and tells them which release of the app they use, for example 2.4.1. The build number identifies a specific build and is required by mobile app stores, for example versionCode on Android or CFBundleVersion on iOS. One version can therefore have several builds.
When should I bump the major version?
Under SemVer, with every change that isn't backward compatible: a removed or renamed API, a changed data format or behavior the consumers of your app rely on. In practice, bumping the major version signals that some rules and expectations are changing, and consumers of your app will have to account for them in their own apps. Minor and patch reset to zero, so 1.7.3 becomes 2.0.0.
Should I use SemVer or CalVer?
SemVer if another app depends on yours or compatibility matters, typically for libraries and public APIs. CalVer if you release regularly and users mostly care about how old the app is, typically for web and internal apps.
Can I start with version 0.x?
Yes. SemVer reserves 0.x versions for initial development, when the app or its interface can change at any time. Use 1.0.0 once real users rely on the app, because from that point on you commit to compatibility.
Do all customers have to run the same version?
No, it's common for several versions of one app to be in use across different customers. In practice, production will often run a different version than the test environment, which usually has a newer one. Customers often update their apps according to their own rules and capacity, so having an overview of deployed versions is useful.
How should I version an app with a separate frontend, backend or several services?
It depends on how you organize the development and deployment of the individual parts. As a rule, every service, module or part that is deployed on its own should have its own version. If the app lives in a so-called monorepo and you deploy all its parts together, one shared version for the whole app is fine.
How do I start versioning an existing app? Do I need to reconstruct the version history?
You don't need to reconstruct the version history. Pick a versioning scheme and release your first version. From that point on, you start tracking new changes in the app. If the app went through major changes you consider worth documenting, you can assign versions to those changes retroactively.
In short
App versioning comes down to a simple principle: one scheme, a unique number for every version and a list of changes for each one.
Want versions and deployments in one place?
Add your app to AboutTheApp, attach a version with its release notes and assign it to your customers and their environments.