Skip to content
This repository has been archived by the owner on Oct 5, 2018. It is now read-only.

SemVer Support

Jump to bottom
Andrew Oberstar edited this page Feb 11, 2015 · 11 revisions

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 (such as dev, milestone, rc, final). Available stages are configured on the strategies set on the plugin extension.
  • The nearest version is picked from the list of tags that can be parsed as a version. The tag with the fewest number of commits between it and the current HEAD (as determined by a git log) is the nearest.
    • 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

Both properties are optional, in general, but may be required by specific strategies.

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 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 any and nearest normal versions.
  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.

Partial Strategies

After gathering the initial state to use during inference, the SemVerStrategy class delegates to "partial" strategies intended to (but not required to) infer the normal, pre-release, and build metadata components of the version separately.

Multiple strategies can be chained together, if desired, to either:

  • Apply all of the chained strategies in order.
  • Choose one strategy; the first one that modifies the inference state.

Samples

The opinion package provides a bunch of sample strategies (partial and full) that can be used out of the box or as examples for custom approaches.

Clone this wiki locally