SemVer Support

In order to support Semantic Versioning, the semver package provides an implementation of VersionStrategy that allows inference of the components of a semantic version.

Concepts

• A semantic version includes 1-3 components: <normal>[-<pre-release>][+<build metadata>]
• A normal version is the primary component consisting of: <major>.<minor>.<patch>
• The change scope can be either MAJOR, MINOR, or PATCH. The scope determines which piece of the normal version will be incremented.
• The stage of the change corresponds to the development stage. Available stages are configured on the strategies set on the plugin extension.
• The nearest version is determined from the size of the commit logs between tags that can be parsed as version numbers and the current HEAD.
  • The nearest any version is the absolute nearest of any tagged versions.
  • The nearest normal version is the nearest tagged version that only has a normal component.

Project Properties

The following properties can be specified on the command line (or any other Gradle-supported method) as a way to control which version is inferred at build-time.

• release.scope
• release.stage

./gradlew release -Prelease.scope=minor -Prelease.stage=rc

Selection Behavior

When strategies are being selected:

1. Return false, if the project's release.stage property isn't set to one listed in the strategy's stages property.
2. Return false, if the repo has uncommitted changes and the strategy has allowDirtyRepo to be set to false.
3. Return false, if the current branch is behind its tracked counterpart and the strategy has allowBranchBehind set to false.
4. Return true.

Inference Behavior

When a version is inferred:

1. Get the scope specified in the release.scope property of the project, if set.
2. Get the stage specified in the release.stage property of the project, if set. If it's not set, default to the first stage in the configured SortedSet. The first will be the one with the lowest precedence according to SemVer.
3. Determine the "nearest" version by looking at the commit logs of each tagged version to the current HEAD in the repository. The tag with the shortest commit log will be considered the nearest "any" version. The nearest "normal" is the tag corresponding to a "normal" version with the shortest commit log.
4. Next the configured partial strategies will be applied in normal, pre-release, and build metadata order.
5. If the strategy enforces version precedence the inferred version will be compared against the nearest "any" version. If the inferred version is less than the nearest any, an exception will be thrown.
6. The inferred version will be returned.