Phase 5: Testing, CI/CD & App Store

Semantic versioning, release notes & phased rollouts

Intermediate ~3 min read
Think of it this way A friendly analogy. Read this if the technical version feels dense. Show Hide

You know how much fun it is to build amazing things with LEGOs, right? Maybe you've built a super cool spaceship or a giant castle. Well, making computer apps is kind of like building with digital LEGOs. You start with an idea, put pieces together, and eventually, you have something awesome. But just like with LEGOs, you often want to improve your app, add new rooms to your castle, or give your spaceship cooler engines. How do you tell everyone who uses your app what has changed without them getting confused about whether their old castle pieces still fit the new design? That's where special version numbers come in!

Imagine you have instructions for building your favorite LEGO spaceship, let's call it the "Star Explorer." When you first build it, the instructions might say "Star Explorer Version 1.0.0." If you later add a brand-new, amazing laser turret that easily snaps onto your existing ship, the instructions might change to "Star Explorer Version 1.1.0." The first number (1) means it's still fundamentally the same great ship, and the second number (1) means there's a cool new part that works perfectly with what you already have. Now, if the designers realize a small piece on the wing kept falling off, and they update the instructions to fix just that tiny problem, it might become "Star Explorer Version 1.1.1." The last number means it's a small fix, nothing new, but making what's there work better.

But what if the designers decide to make a completely new Star Explorer? Maybe it's much bigger, uses different types of blocks, and doesn't really fit with any of your old accessories. Then the instructions would jump to "Star Explorer Version 2.0.0." That big first number (from 1 to 2) tells you instantly: "Whoa, this is a major change! This might be a totally different building experience, and your old pilots might not even fit in the new cockpit!" It's important to know this so you can decide if you want to get the new instructions and rebuild, or stick with your classic ship.

Along with these clever version numbers, app creators also write little messages called "release notes." These are like a short, friendly letter from the LEGO designer that comes with the new instructions. They tell you exactly what's new, what's been fixed, and what's better in simple words. For example, "We fixed that wobbly wing!" or "Now with an awesome new laser turret!" These notes help people using the app understand if they should update, what cool new things they'll get, or if a bug they reported has been fixed. So, when you eventually build your own amazing apps, using these version numbers and writing clear release notes will help you tell your users all about your fantastic creations and keep everyone happy and informed!

When preparing your mobile app for submission, understanding Semantic Versioning (SemVer) is crucial for communicating changes effectively. SemVer uses a MAJOR.MINOR.PATCH format (e.g., 1.2.3) to indicate the nature of an update. A MAJOR version increment (1.x.x to 2.x.x) signals breaking changes or significant new features. A MINOR increment (x.1.x to x.2.x) indicates new, backward-compatible features. A PATCH increment (x.x.1 to x.x.2) is reserved for backward-compatible bug fixes or minor performance improvements. Adhering to SemVer helps users understand what to expect from an update and helps you manage compatibility between app versions and APIs.

Alongside versioning, well-crafted release notes are vital. These notes serve as your primary communication channel with users and app store reviewers, detailing what's new, improved, or fixed in each version. For users, clear and concise release notes highlight new features they can enjoy and assure them that reported issues are being addressed, encouraging updates. For app store reviewers, they provide a quick overview of changes, potentially streamlining the review process. Always focus on user-facing benefits, avoid internal jargon, and keep them fresh for every release, even if it's just bug fixes. Generic notes like "bug fixes and performance improvements" are less effective than specific descriptions.

Finally, phased rollouts (also known as staged rollouts) are a strategic approach to deploying app updates, particularly for major releases. Instead of releasing to 100% of your user base simultaneously, a phased rollout gradually makes the update available to a small percentage of users (e.g., 1-5%), then progressively increases that percentage over days or weeks. This strategy minimizes risk by allowing you to monitor for unexpected bugs, performance regressions, or crashes with a limited audience. If issues arise, you can pause or halt the rollout, fix the problem, and then resume, preventing a poor experience for all users. Both Google Play and Apple TestFlight (and sometimes direct App Store functionality) offer tools to manage phased rollouts effectively.

Key Takeaways

  • Semantic Versioning (MAJOR.MINOR.PATCH) communicates the scope and impact of an update to users and developers.
  • Clear, concise, and user-focused release notes are essential for user engagement and smooth app store reviews.
  • Phased rollouts mitigate risk by gradually exposing updates to users, allowing for early detection and resolution of issues.
  • Consistent versioning and informative release notes build user trust and encourage app updates.
  • Leverage app store features for managing phased rollouts to ensure a stable user experience.

Code Example

groovy
android {
    compileSdk 34

    defaultConfig {
        applicationId "com.kunalganglani.myapp"
        minSdk 24
        targetSdk 34
        versionCode 1020304 // Internal build number, always increments (e.g., 1.2.3.4)
        versionName "1.2.3" // Semantic Versioning: MAJOR.MINOR.PATCH
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

How this code works

This Groovy code block establishes fundamental configuration settings for an Android application, directly impacting its compatibility, behavior, and how it's identified and managed on app stores. Settings like compileSdk and targetSdk define which Android platform versions the app is built against and designed to run on, ensuring access to modern features and security updates. The applicationId serves as the app's unique identifier on Google Play, a non-negotiable requirement for submission, while minSdk specifies the oldest Android version capable of running the app. Most critically for releases, versionCode is an internal, always-incrementing integer used by app stores to track each unique build submission, whereas versionName is the public, user-facing semantic version string (e.g., "1.2.3").

The buildTypes block configures various ways to compile the app, with the release configuration specifically tailored for app store distribution. Within release, options like minifyEnabled and proguardFiles are set to optimize the app by reducing its size and obfuscating its code, which improves performance and security for the final production build. A subtle but vital detail for beginners is that versionCode must always be increased for every new app upload to an app store, even for minor internal changes that don't alter the versionName. This ensures the store can differentiate and manage every single build, preventing issues during phased rollouts or updates, irrespective of how the user-visible versionName follows its semantic versioning rules.

Related Articles

Hand-picked reads to go deeper on app store submission & review.

Back to Mobile Developer Roadmap