Mobile App Versioning

Mobile app versioning, also called app version management, is the process of assigning a distinct identifier to each release of a mobile application, usually represented as a version number such as 1.0.0, 1.1.0, or 2.0.0. This system helps both developers and users track the evolution of an app and understand the scope of changes in each release. Versioning supports bug fixes, feature additions, performance improvements, and security updates while ensuring compatibility across devices and platforms.

Proper versioning is essential for maintaining and updating mobile applications effectively. It allows teams to manage updates, track releases, and coordinate between iOS and Android. There are several strategies for versioning applications, with the most common being Semantic Versioning (SemVer) and Calendar Versioning (CalVer).

Semantic Versioning (SemVer) is a widely used system that assigns version numbers based on the type and impact of changes in a release. A SemVer identifier follows the format: MAJOR.MINOR.PATCH

• MAJOR increases when breaking or incompatible changes are introduced.

• MINOR increases when new features are added in a backward-compatible way.

• PATCH increases when backward-compatible bug fixes are made.

Optional tags can indicate pre-release versions (such as -alpha or -beta) or build metadata (such as +build45).

Example: An app at version 2.1.5 receives a new release. Depending on the type of changes made, the next version could become 2.1.6, 2.2.0, or 3.0.0.

Calendar Versioning (CalVer) is a versioning scheme where releases are identified by dates rather than by code or feature changes. In CalVer, the version number indicates the passage of time, making it clear when a release was published instead of tying it to specific code-level or feature-level changes. Common formats include:

• YY.MM → 25.09 for a release in September 2025

•YYYY.MM.DD → 2025.09.15 for a release on September 15, 2025.

• YYYY → 2025 for a yearly release

This approach is popular for projects that release on a fixed schedule, since it's easy to understand when the release occurred.

Example: A team using CalVer might release version 2025.09 in September 2025. Their next update in November would be 2025.11, regardless of whether the changes were bug fixes, new features, or breaking updates.

Different projects adopt versioning strategies based on their needs. Semantic Versioning (SemVer) is widely used in open-source libraries, APIs, and SDKs where compatibility and dependency management are critical. Calendar Versioning (CalVer) is often chosen by operating systems, browsers, and enterprise software that release on fixed schedules. For mobile apps, the best approach might be SemVer.

Why SemVer works best for iOS versioning and Android versioning:

• The App Store and Google Play require strictly incrementing version numbers, which fits naturally with SemVer.

• It clearly communicates the type of update: bug fix, new feature, or major change.

• It aligns mobile releases with backend services, APIs, and third-party libraries that already follow SemVer.

• Users get meaningful version numbers when reviewing release notes.

Example: A team releases a consumer app to the App Store with version 2.4.0. A small bug fix bumps it to 2.4.1, while a new feature moves it to 2.5.0. This SemVer pattern fits App Store rules and communicates changes clearly to users. By contrast, an enterprise IT department distributing an internal app every quarter might use CalVer, naming releases 2023.09, 2023.12, and 2024.03 to reflect when updates go out.

Every mobile app release is identified by two values: the version number and the build number. These two values serve different purposes.

• Version Number (iOS: CFBundleShortVersionString, Android: versionName): This is the public-facing version that users see in the App Store or Google Play, such as 2.3.1. It usually follows Semantic Versioning (MAJOR.MINOR.PATCH) to indicate the type of change: a bug fix, a new feature, or a major update.

• Build Number (iOS: CFBundleVersion, Android: versionCode): This is the internal identifier required by the app stores. It must increase with every submission so the store can recognize each release as newer than the last. Build numbers are not visible to users but are critical for successful uploads to TestFlight and Google Play.

Example: A team publishes version 1.2.0 (build 15). When they fix a bug, they release 1.2.1 (build 16). Later, they add a new feature and ship 1.3.0 (build 17). End users only see the version numbers (1.2.0, 1.2.1, 1.3.0) in the store, while the build numbers (15, 16, 17) ensure each update is accepted in sequence.

Consistent versioning helps both app stores and users understand the scope of each release. Following Semantic Versioning (SemVer) principles, updates are categorized as MAJOR, MINOR, or PATCH changes:

• MAJOR version (1.x.x): Increase the major version when you introduce breaking changes or significant new functionality that is not backward compatible. These updates may change how existing features behave and could require users to adapt.

• MINOR version (x.1.x): Increase the minor version when you add new features in a backward-compatible way. These releases expand functionality without breaking existing features.

• PATCH version (x.x.1): Increase the patch version when you release bug fixes, small improvements, or performance enhancements that do not affect compatibility.

Example: A development team configures their versioning strategy once using Appcircle. From that point on, Appcircle automatically manages version numbers and build numbers for every build and release, aligning with the industry best practices. Developers no longer need to worry about manual updates or risk rejections from the App Store and Google Play due to versioning errors.