Skip to content

Latest commit

 

History

History
302 lines (220 loc) · 10.2 KB

README.md

File metadata and controls

302 lines (220 loc) · 10.2 KB
Raw

License (3-Clause BSD) Quality Gate Status Build Status CircleCI Gradle

Semantic Version Plugin for Gradle

A Semantic Version Plugin for Gradle that manages a project version via a properties file, and provide tasks to automatically increment major, minor, patch and build version numbers.

The plugin can be used in conjunction with the Semantic Version Annotation Processor.

Using the plugin

The plugin is published to the Plugin Portal; see instructions there: net.thauvin.erik.gradle.semver

Version Properties File

By default, a properties file named version.properties will be created when Gradle is run:

#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=
version.buildmeta=
version.semver=1.0.0

To change the version of your project, remove the version from build.gradle and simply edit the version properties file to match your version number.

If you need to change the properties file or name of the properties keys to match your own build environment. Please see the Configuration section.

Increment Version Tasks

incrementMajor, incrementMinor and incrementPatch

The incrementMajor, incrementMinor and incrementPatch tasks are available to automatically increment their respective and reset lower counterpart version numbers.

  • incrementMajor will increment the major and set the minor and patch versions to 0.
  • incrementMinor will increment the minor and set the path version to 0.

Examples

./gradlew incrementPatch ...

or in your gradle.build file:

someTask {
    dependsOn(incrementPatch)
    ...
}

incrementBuildMeta

The incrementBuildMeta task is available to set the build metadata version to a custom calculated value.

Examples:

To set the build metadata to a custom formatted date:

incrementBuildMeta {
    doFirst {
        buildMeta = new Date().format("yyyyMMddHHmmss")
    }
}
./gradlew incrementBuildMeta

...

> Task :incrementBuildMeta
Version: 1.0.16-beta+20180713143416

Or to set the build metadata to a custom formatted number with increment:

incrementBuildMeta {
    doFirst {
        buildMeta = sprintf("%03d", (buildMeta as Integer) + 1)
    }
}
./gradlew incrementBuildMeta

...

> Task :incrementBuildMeta
Version: 1.0.16-beta+002

Command Line

The major, minor, patch, prerelease and buildmeta versions can also be set via the command line:

./gradlew -Dversion.prerelease=beta -Dversion.buildmeta= ...
#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta
version.buildmeta=
version.semver=1.0.0-beta

The full semantic version can also be specified via the semver property:

./gradlew -Dversion.semver=1.0.0-beta ...

If a version cannot be parsed your build will fail.

Configuration

Version File Properties

The following default properties are recognized:

Property Description Default
version.major The major version. 1
version.minor The minor version. 0
version.patch The patch version. 0
version.prerelease The pre-release version
version.prerelease.prefix The pre-release prefix -
version.buildmeta The build metatdata version
version.buildmeta.prefix The build metadata prefix +
version.separator The version separator. .

The version number is built as follows:

version.major version.separator version.minor version.separator version.patch [ version.prerelease.prefix version.prerelease ] [ version.prerelease.prefix version.buildmeta ]

For reference, it is automatically included in the version.semver property.

for example:

#version.properties
version.major=1
version.minor=0
version.patch=0
version.prerelease=beta
version.buildmeta=exp.sha.5114f85
version.semver=1.0.0-beta+exp.sha.5114f85

project.version will be 1.0.0-beta+exp.sha.5114f85 in Gradle.

Semver

In a Gradle build file, the semver block is used to configure how the plugin will read/write the version properties file. In most cases it is not needed.

But, for example, if you wanted to save the version properties in a different file:

semver {
    properties = "my.version" // read and save properties in "my.version"
}

or using different property keys for the version data:

semver {
    keysPrefix = "" // no prefix
    semverKey = "version"
    majorKey = "maj"
    minorKey = "min"
    patchKey = "build"
    preReleaseKey = "rel"
    buildMetaKey = "meta"
}

which would match the data in my.version:

#my.version
maj=1
min=0
build=0
rel=beta
meta=
version=1.0.0-beta

The following semver properties are available:

Property Description Default
properties The properties file. version.properties
semverKey The semver property key. version.semver
majorKey The major property key. version.major
minorKey The minor property key. version.minor
patchKey The patch property key. version.patch
preReleaseKey The pre-release property key. version.prerelease
preReleasePrefixKey The build pre-release prefix key. version.prerelease.prefix
buildMetaKey The build metadata property key. version.buildmeta
buildMetaPrefixKey The build metadata prefix property key. version.buildmeta.prefix
separatorKey The separator property key. version.separator
keysPrefix The prefix for all property keys. version.

In order to quickly support multiple projects. The keysPrefix property is available to set all properties keys prefixes at once:

semver {
    properties = "test.properties"
    keysPrefix = "test."
}
#test.properties
test.major=1
test.minor=0
test.patch=0
test.prerelease=
test.buildmeta=
test.semver=1.0.0

Semver Extension Properties

The values stored in the version properties file can individually be accessed using the semver extension, for example:

    fooTask {
        doFirst {
            println "Build: $semver.buildMeta"
        }
    }

The semver extension properties are:

Property Description
semver.semver The full semantic version.
semver.version Same as semver.semver.
semver.major The major version.
semver.minor The minor version.
semver.patch The patch version.
semver.preRelease The pre-release version
semver.preReleasePrefix The pre-release prefix
semver.buildMeta The build metatdata version
semver.buildMetaPrefix The build metadata prefix
semver.separator The version separator.

Version is "unspecified"

This is a common problem stemming from the configuration and build phases in Gradle.

It is always preferable to access to version during the execution stage, in a doFirst or doLast closure within your tasks:

task foo() {
    doFirst {
        println project.version
    }
}

or if absolutely necessary, at the end of the configuration stage in a project.afterEvaluate block:

foo {
    project.afterEvaluate {
        println project.version
    }
}

Source Code Generation

If you'd like to incorporate the version number data into your source code, please have a look at the Semantic Version Annotation Processor.

There are also full examples in both Java and Kotlin showing how to use both the plugin and annotation processor concurrently.