SUPERCILEX/version-orchestrator

Version Orchestrator provides an effortless and performant way to automate versioning your Android app.

Version Orchestrator

Version Orchestrator provides an effortless and performant way to automate versioning your Android app.

Table of contents

1. How does it work?
   1. Version codes
   2. Version names
2. Installation
   1. Snapshot builds
3. Configuring Version Orchestrator
   1. Disabling version code configuration
   2. Disabling version name configuration
   3. Enabling debug build configuration
   4. For existing apps

How does it work?

Version Orchestrator looks at your Git history to compute a version code and name for your app.

Version codes

The version code is a combination of the number of commits in your repository and your tag history, enabling support for hotfix releases. The math looks a little like this:

versionCode = existingAppOffset +
        commitCount +
        numberOfNonPatchTags +
        100 * numberOfNonPatchTagsMinusOneIfIsRelease

For example, you have 4 commits and tag a 1.0.0 release (versionCode = 5). On your 5th commit, the version code will jump to 106. You continue making commits until you realize a critical bug needs to be fixed. Branching off the 1.0.0 release, you fix the bug and tag your 1.0.1 hotfix (versionCode = 6). After merging the hotfix and 3 other commits from your new features back into master, you create a 1.1.0 release (versionCode = 110). On your 11th commit, the version code will jump to 211. This continues on, allowing you to make 100 patch releases for each major or minor release.

Version names

The version name is a combination of the latest tag, commit hash, dirtiness flag, and variant name. Currently, it is calculated using git describe and your buildType name plus productFlavor name (if present).

Installation

Apply the plugin to each individual com.android.application module where you want to use Version Orchestrator through the plugins {} DSL:

Kotlin

plugins {
    id("com.android.application")
    id("com.supercilex.gradle.versions") version "0.10.0"
}

Groovy

plugins {
    id 'com.android.application'
    id 'com.supercilex.gradle.versions' version '0.10.0'
}

Snapshot builds

If you're prepared to cut yourself on the bleeding edge of Version Orchestrator development, snapshot builds are available from Sonatype's snapshots repository:

Kotlin

buildscript {
    repositories {
        // ...
        maven("https://oss.sonatype.org/content/repositories/snapshots")
    }

    dependencies {
        // ...
        classpath("com.supercilex.gradle:version-orchestrator:1.0.0-SNAPSHOT")
    }
}

Groovy

buildscript {
    repositories {
        // ...
        maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
    }

    dependencies {
        // ...
        classpath 'com.supercilex.gradle:version-orchestrator:1.0.0-SNAPSHOT'
    }
}

Configuring Version Orchestrator

Version Orchestrator offers several options to fit your use case.

Disabling version code configuration

To handle version codes yourself, disable version code configuration:

versionOrchestrator {
    configureVersionCode.set(false)
}

Disabling version name configuration

To handle version names yourself, disable version name configuration:

versionOrchestrator {
    configureVersionName.set(false)
}

Enabling debug build configuration

To make debug builds as fast as possible, version codes and names are never changed in debug builds by default. To enable versioning, enable debug build configuration:

versionOrchestrator {
    configureDebugBuilds.set(true)
}

For existing apps

If your app already has an established version code, you can tell Version Orchestrator about it:

versionOrchestrator {
    versionCodeOffset.set(123)
}