Git sensitive Semantic Versioning (SemVer) Gradle Plugin for Android

A Gradle plugin that forces semantic versioning in an Android project (version name and version code) and relies on git to detect the project state, based on Git-Sensitive Semantic Versioning Plugin by Danilo Pianini .

Rationale

Semantic Versioning introduces a way to meaningfully version software. At the same time, git carries the project history with it. It sounds rather reasonable to mix them together, and have the project react to the git status.

This plugin assumes you use git tags to mark releases, by tagging your project with tag names such as 0.1.2. It then uses git to compute the version, in terms of both git hash and distance from the latest tag.

The plugin generates the following:

• "Archeo" versions for the development before initializing git, in the form of 0.1.0-archeo+time
• "Pre-development" versions for the development before marking the first release, in the form of 0.1.0-dev+hash
• "Stable" versions if a tag is present, in the form 0.1.0
• "Development" versions for changes over a tag, in the form 0.1.1-dev01-hash, with the number after dev counting the distance in commits since the last tag.

Usage

Importing the plugin

In your build.gradle.kts file of the app module add the following:

plugins {
    id("io.github.andreabrighi.android-git-sensitive-semantic-versioning-gradle-plugin") version "1.0.2"
}
// Rest of your buildscript

...
androidGitSemVer {
    // Your configuration
}
...
    android {
        defaultConfig {
            ...
            versionCode = androidGitSemVer.computeVersionCode()
            versionName = androidGitSemVer.computeVersion()
        }
    }

Plugin options

androidGitSemVer {
    minimumVersion.set("0.1.0")
    developmentIdentifier.set("dev")
    noTagIdentifier.set("archeo")
    fullHash.set(false) // set to true if you want to use the full git hash
    maxVersionLength.set(Int.MAX_VALUE) // Useful to limit the maximum version length, e.g. Gradle Plugins have a limit on 20
    developmentCounterLength.set(2) // How many digits after `dev`
    enforceSemanticVersioning.set(true) // Whether the plugin should stop if the resulting version is not a valid SemVer, or just warn
    // The separator for the pre-release block.
    // Changing it to something else than "+" may result in non-SemVer compatible versions
    preReleaseSeparator.set("-")
    // The separator for the build metadata block.
    // Some systems (notably, the Gradle plugin portal) do not support versions with a "+" symbol.
    // In these cases, changing it to "-" is appropriate.
    buildMetadataSeparator.set("+")
    distanceCounterRadix.set(36) // The radix for the commit-distance counter. Must be in the 2-36 range.
    // A prefix on tags that should be ignored when computing the Semantic Version.
    // Many project are versioned with tags named "vX.Y.Z", de-facto building valid SemVer versions but for the leading "v".
    // If it is the case for some project, setting this property to "v" would make these tags readable as SemVer tags.
    versionPrefix.set("")
    // This reproduces the behavior of the plugin at version 0.x.y: ignores non-annotated (lightweight) tags.
    excludeLightweightTags()
    // Compute the next upgrade type (major/minor/patch) based on commit messages; defaults to patch regardless of the commits.
    commitNameBasedUpdateStrategy { UpdateType.PATCH }
}

Code Version computation

The plugin computes the version code by using two algorithms: - The first one is based on the number of commits in the current branch (default). - The second one is based on the version name.

To use the second algorithm:

androidGitSemVer {
    incrementalCode.set(false) // Whether the version code should be use semantic versioning
    versionCodeMajorDigits.set(3) // How many digits for the major version (default 3)
    versionCodeMinorDigits.set(3) // How many digits for the minor version (default 3)
    versionCodePatchDigits.set(3) // How many digits for the patch version (default 3)
}

Manually forcing the version computation early

The plugin sets the project version by scheduling a call to the assignGitSemanticVersion() using project.afterEvaluate. This should be fine for most use cases, but you might need the version of the project to be set early in the configuration phase. If so, you can manually call assignGitSemanticVersion() from within the plugin configuration block, after all options have been configured (if any configuration was performed):

androidGitSemVer {
    // Your configuration
    assignGitSemanticVersion()
}

Inside the configuration block is also available the computeVersion() is also available to recompute (but do not set) the version.

Manually force the version

The plugin allows to manually set the version via a gradle property that, if present, will be used as the version of the project. By default, the property name is forceVersion, but you can change the property name by setting the forceVersionPropertyName property of the plugin with a custom name.

./gradlew -PforceVersion=1.2.3 <task list> will result in the project version being set to 1.2.3.

If a custom property name is used, the plugin will look for the property with the given name:

androidGitSemVer {
    forceVersionPropertyName.set("myCustomPropertyVersion")
}

./gradlew -PmyCustomPropertyVersion=1.2.3 <task list> will result in the project version being set to 1.2.3.

Using conventional commits?

This plugin can be configured to use the conventional commits to determine the next version through another plugin. Visit the conventional commits extension for git-sensitive-semantic-versioning-gradle-plugin to learn more.