Changelog

In the previous chapter, we discussed how to update Android apps to deliver improved user experiences and new features. In this chapter, we focus on version management—a critical practice that ensures your app is accurately identified, tracked, and managed throughout its release and update lifecycle.

Why Version Management Matters

Version management is essential in Android app development. From the initial build through every subsequent update, clear and consistent versioning helps developers, users, and app stores efficiently organize, distribute, and track app releases.

Understanding Version Identifiers

In Android development, an app’s version is defined by two key properties: versionCode and versionName.

• versionCode is an integer value that must increase with each new release. It serves as an internal, machine-readable identifier used by Google Play and other distribution platforms to determine version precedence and enforce upgrade ordering.
• versionName is a human-readable string (e.g., "1.0.0") displayed to users. While commonly formatted as X.Y.Z, it has no impact on version sorting—it’s purely for communication.

For example, in your build.gradle file, version configuration might look like this:

android {
    ...
    defaultConfig {
        ...
        versionCode 2
        versionName "1.1.0"
    }
}

Best Practices for Version Management

1. Update versionCode and versionName Consistently

Always increment both versionCode and versionName before releasing a new version. For instance, after adding features or fixing multiple bugs, increment versionCode (e.g., from 2 to 3) and update versionName to reflect the nature of the changes (e.g., "1.1.0" → "1.2.0").

2. Adopt Semantic Versioning

We strongly recommend following Semantic Versioning (SemVer) conventions (MAJOR.MINOR.PATCH). This standard clarifies the scope and impact of each release:

• MAJOR (e.g., 2.0.0): Incremented when introducing breaking, backward-incompatible API changes.
• MINOR (e.g., 1.1.0): Incremented when adding new features without breaking existing functionality.
• PATCH (e.g., 1.0.1): Incremented for backward-compatible bug fixes only.

For example, upgrading from 1.0.0 to 1.1.0 signals that new features have been added while preserving full compatibility with prior versions.

3. Maintain a Changelog

A dedicated CHANGELOG.md file helps teams document changes per release. It supports internal collaboration, informs users about updates, and strengthens transparency in marketing and support.

# Changelog

## [1.1.0] - 2023-10-01
### Added
- New user feedback feature

### Fixed
- Resolved app crash issues

The App Release Workflow

When managing versions, follow this standard release process:

1. Bump Versions: Update versionCode and versionName in build.gradle.

2. Build APK/AAB: Generate the final production artifact—either an APK or, preferably, an Android App Bundle (AAB)—using Android Studio or Gradle:

   ./gradlew assembleRelease
   

3. Test Thoroughly: Validate the new version across target devices and configurations before publishing to production.

4. Upload to Store: Submit the APK/AAB to Google Play Console (or another distribution platform), verifying metadata—including title, description, screenshots, and version details.

5. Publish: Finalize and roll out the release via the store’s version management dashboard.

Managing Compatibility Across Devices and OS Versions

Android apps must account for diverse hardware and Android OS versions. Key compatibility considerations include:

• Target SDK Version: Set targetSdkVersion in build.gradle to indicate the latest Android API level your app is optimized for—and to comply with platform requirements.

• Minimum SDK Version: Define minSdkVersion to specify the oldest Android version your app supports. This ensures installation only on compatible devices.

• Compatibility Testing: Test rigorously across Android versions using tools such as the Android Emulator, Firebase Test Lab, or physical devices.

android {
    ...
    defaultConfig {
        ...
        minSdkVersion 21 // Android 5.0 (Lollipop)
        targetSdkVersion 31 // Android 12
    }
}

Conclusion

Thoughtful version management lays the foundation for stable, scalable, and user-friendly Android app releases. By mastering the concepts and practices covered in this chapter—semantic versioning, changelog discipline, compatibility planning, and structured release workflows—you’ll ensure smooth, reliable delivery of every update.

Next, in Chapter 9, we’ll dive deeper into advanced topics—specifically, leveraging and managing Android Jetpack components to accelerate development and enhance app quality.