Maven CI-Friendly Versions

Since Maven 3.5.0 (see Versions & Release History) the properties ${revision}, ${sha1} and ${changelist} may be used in the version element of a POM, including the version of the parent reference and the version of the project itself. They are special only because Maven allows them there: a version otherwise has to be a constant, and a POM that puts any other expression in version gets a warning, shown below. The names suggest a division of the version into parts that a pipeline can set separately:

The three can be used alone or concatenated in the version, as ${revision}${sha1}${changelist}. The properties of the version that is not needed are left empty, with an empty element such as <sha1/>. The value is built from them as plain text, so the leading dash of -SNAPSHOT or of -6275f0f belongs to the property value, not to the version template.

Source: Maven CI friendly versions: Single project setup

The version of a project is ${revision}, and the default value is a property of the POM:

The property can be overridden with -D, because a user property takes precedence over a property of the POM:

(only the lines that name the version are shown.) The value 1.0.0-SNAPSHOT in the POM is a convenience for developers who just run mvn package. The pipeline always passes its own. For a project that needs a finer division, the three properties are concatenated:

and the command line chooses what is a release and what is a snapshot. These are the file names of the jars built in the multi-module tidepool project below, with these five commands:

-Dchangelist= sets the property to the empty string, which is how a release build removes the -SNAPSHOT qualifier. The command-line arguments can also be put in a file, .mvn/maven.config in the root of the project, one argument per line:

(see Configuring Maven). With that file, mvn clean package built tidepool-model-1.3.0-SNAPSHOT.jar, and the extra argument -Dchangelist= on the command line, which comes after the file’s content, built tidepool-model-1.3.0.jar.

Source: Maven CI friendly versions: Single project setup

The guide states that only the properties revision, sha1 and changelist can be used, and not other names. The check was to use ${tide.version} as the version of the parent and of both modules in the multi-module POM. Maven 3.10.0 still built it, but each POM was reported with a warning:

The warning means "this is not a supported setup": the build may work, and the published POM is not usable (see Install and deploy: why Maven 3 needs the flatten plugin). Use the three names. The guide gives a second example of what not to do: a property that is built from another one, such as <revision>1.0.0-${buildNumber}-SNAPSHOT</revision>, does not work as expected, so combine the three standard properties instead.

Source: Maven CI friendly versions: Single project setup

In a multi-module build (see Multi-Module Builds & the Reactor and Inheritance, Aggregation & the Effective POM) the parent declares the property, and every module repeats the placeholder in its parent reference:

A module does not declare its own version; it inherits the parent’s. The module tidepool-engine depends on tidepool-model, and the version there must be ${project.version}, the usual way of keeping modules in step:

The guide warns that ${revision} instead of ${project.version} fails the build. That is true when the three properties are combined in the version, as here, because ${revision} alone is 1.0.0, not 1.0.0-SNAPSHOT: the module tidepool-model is then looked for in the repositories, with this real result on Maven 3.10.0:

With ${project.version}, the reactor sorted the modules and built them in order, for every value of the properties above. The prefixes line comes from the repository prefix filtering that Maven 3.10 does for Maven Central (see Maven Resolver).

Source: Maven CI friendly versions: Multi-module setup (Maven 3), Dependencies

Building and testing with a placeholder version is enough for a pipeline that never publishes. As soon as the artifacts are installed or deployed, the problem appears: Maven copies the file pom.xml as it is, so the repository holds a POM whose parent version is still the text ${revision}${sha1}${changelist}, and nobody can resolve it. The multi-module project was deployed with mvn -Drevision=1.2.0 -Dchangelist= deploy -DaltDeploymentRepository=local::file://$W/repo-noflat, and the deployed POM of tidepool-engine read:

A consumer that depends on io.tidepool:tidepool-engine:1.2.0 from that repository failed on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7 alike:

(on Maven 4.0.0-rc-7 the same cause is followed by the list of repositories that were asked; Maven 3.9.16 failed at the same step with Failed to read artifact descriptor.) The jars are correct, and the metadata is wrong.

The cure on Maven 3 is the flatten-maven-plugin of MojoHaus. It writes a copy of the POM in which the placeholders are replaced by their values, and makes that copy the POM that is installed and deployed. The plugin is declared once, in the parent. This is the configuration of the guide with the current plugin version (1.8.0 here):

With updatePomFile, the generated flattened POM is set as the POM file of the project, which is what install and deploy then publish. flattenMode says how much to flatten. resolveCiFriendliesOnly only resolves the variables revision, sha1 and changelist and keeps everything else, which is what the CI-friendly setup needs; the other modes (oss, ossrh, bom, defaults, clean and fatjar) also remove optional elements of the POM, and are meant for publishing a trimmed POM. By default the plugin replaces the POM only for projects whose packaging is not pom, so updatePomFile is set to true here to flatten the pom packaging parent as well. Since plugin version 1.8.0 the parameter revisionVariableName (user property flatten.revision.variable.name) names the variable that is used as the version in this mode; it defaults to revision. The flatten.clean execution removes the generated file, .flattened-pom.xml, on mvn clean. That file is created in every module, including the root, so add it to .gitignore.

The log of mvn -Drevision=1.2.0 -Dchangelist= clean deploy ... with the plugin (a selection of its lines):

and the deployed POM of tidepool-engine became:

The parent version is now the constant 1.2.0, and ${project.version} in the dependency is still an expression, which is correct: project.version is a property that every Maven resolves from the POM it reads, not a placeholder of the build. A consumer on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7 resolved tidepool-engine and tidepool-model at 1.2.0 from this repository. The deployed parent POM kept the property <revision>1.0.0</revision> from the source, which is harmless because nothing uses it any more, but it is misleading to a reader. The deployed POM of tidepool-engine from Maven 3.9.16 was identical.

Source: Maven CI friendly versions: Install / Deploy, Flatten plugin: flatten goal

Maven 4 (release candidate) takes the flattening of CI-friendly versions into the build itself, together with two other changes. With model version 4.1.0 a module does not need to say the version of its parent, nor the version of a dependency on another module of the same build (automatic version resolution), and the modules are called subprojects (see Maven 4: POM Model & Consumer POM). The same tidepool project, without the flatten plugin:

mvn -Drevision=1.2.0 -Dchangelist= deploy on Maven 4.0.0-rc-7 deployed, for each module, the jar and two POMs: tidepool-engine-1.2.0.pom (the consumer POM, which is what other builds read) and tidepool-engine-1.2.0-build.pom (the build POM, a copy of the POM as written, with the model version 4.1.0 and without the versions). The consumer POM had no placeholder left, with a model version that a Maven 3 client understands:

The deployed parent POM also had its properties set to the values of the build (<revision>1.2.0</revision> and an empty <changelist>). A consumer on Maven 3.10.0 and on 4.0.0-rc-7 resolved tidepool-engine:1.2.0 and tidepool-model:1.2.0 from this repository.

Maven 4.0.0-rc-7 did the same for the Maven 3 style POMs of the previous section (model version 4.0.0, ${project.version} in the dependency, no flatten plugin): mvn -Drevision=1.2.0 -Dchangelist= deploy deployed a tidepool-engine-1.2.0.pom whose parent version was 1.2.0, and the dependency kept the expression ${project.version}. So the flatten plugin can be dropped as soon as the build runs on Maven 4, even before the POMs move to model version 4.1.0. The details of the consumer POM and the other model changes are on Maven 4: POM Model & Consumer POM, and a path from Maven 3 to 4 is on Migrating to Maven 4.

Source: Maven CI friendly versions: Multi-subproject setup (Maven 4), What’s new in Maven 4

The reason for the three properties is a pipeline that builds a release from a tag, with no release commit. Here is a small script (it is the tidepool one, run in a scratch git repository without a remote): the tag decides what is built.

With the commit tagged v1.4.0, ./release.sh clean deploy ... printed arguments: -Drevision=1.4.0 -Dchangelist=, built tidepool-model-1.4.0.jar and tidepool-engine-1.4.0.jar, and deployed them to a local file:// repository whose directory was io/tidepool/tidepool-model/1.4.0. After an untagged commit, ./release.sh clean package printed arguments: -Dsha1=-6275f0f and built tidepool-model-1.0.0-6275f0f-SNAPSHOT.jar, a snapshot that names the commit it came from. (The hash in your run is different.) The script is this page’s own lab setup, not an example from the Maven documentation.

Source: Maven CI friendly versions: Single project setup

The consequences of this style:

Ant has no versions of artifacts in its build file; a version is a property such as version that can be set on the command line with -Dversion=1.4.0, and there is no consumer POM to repair (see Ant Properties). Gradle reads the version from the build script or from gradle.properties, and a project property such as -Pversion=1.4.0 can supply it when the script does not set it, with the published metadata always written from the resolved value (see Publishing). The mapping is on Repositories & Publishing across Tools.