Specifying Versions To Check

By default, Revapi will automagically figure out the latest released version of your project and check the code that’s been built against it.

This is assumed to be the most common usecase and as such requires no additional configuration. But it always is not exactly what you want.

Specific Old Version

You can choose to explicitly select the old version to check. This is useful in scenarios where you need tell specifically the old version and Maven rules for determining the latest release does not pick the right one.

You can use one of the following configuration parameters of Revapi maven plugin:

  • oldArtifacts - This can be used to precisely specify the GAV (or more GAVs) of the artifact(s) representing your old version.

  • oldVersion - Using this, Revapi will reuse the groupId, artifactId, type and classifier of your currently built artifact and will use the specified version. I.e. using this, you can easily specify the older version of your artifact to check against.

Both of these parameters have their command-line names, too. Please consult the check goal docs for details.

Specific New Version

This is not a very common usecase but you can also specify the new version of the API (i.e. something different than what the Maven just built). Use newArtifacts or newVersion parameters with similar meaning to the old variants.

Leaving Out Pre-releases

Frequently, you will release alpha or beta versions before you release the final version of your project. Maven will consider any non-snapshot release as the latest, but that’s possibly not what you want to check against.

After you release a beta, you still want your project to be checked against the last final release, not against the beta.

You could explicitly specify the oldVersion to be your last final release but the caveat of that is that you will have to remember to change that after you release your new final release (so that your new final release becomes the new baseline for the future development).

There is a simpler way though.

You can use the versionFormat configuration parameter to specify how the version string of the latest release must look like.

For example if you use "GA" as the suffix of your final releases and you released 1.0.GA, 2.0.Alpha and 2.0.Beta, you can configure Revapi maven plugin like this:

<configuration>
  <versionFormat>.*\.GA</versionFormat>
</configuration>

and Revapi will use the latest release that matches that regular expression (which would be 1.0.GA) instead of the latest release as reported by Maven (which would be 2.0.Beta).

Note that the version format applies to both old and new versions and is only taken into account if the version string is one of the Maven’s special version specifiers - RELEASE or LATEST (RELEASE is the default value of oldVersion configuration parameter, so the above configuration will take effect).

Comparing Specific Artifacts

By default Revapi checks the currently built artifact against the latest released version of it. This actually is equivalent to running the maven plugin with the following set up:

<plugin>
  <groupId>org.revapi</groupId>
  <artifactId>revapi-maven-plugin</artifactId>
  <version>{page-component-version}</version>
  <configuration>
    <oldArtifacts>
        <artifact>${project.groupId}:${project.artifactId}:RELEASE</artifact>
    </oldArtifacts>
    <newArtifacts>
        <artifact>${project.groupId}:${project.artifactId}:${project.version}</artifact>
    </newArtifacts>
  </configuration>
  <executions>
    <execution>
      <goals><goal>check</goal></goals>
    </execution>
  </executions>

I.e. the oldArtifacts are set up to include the current project with the RELEASE version, which is Maven’s way of saying "this project in the latest released version". The newArtifacts specifies the currently built project.

The above example implies a couple of things:

  • you can include more than one artifact to be included in the analysis

  • you don’t have to specify the "supplementary archives" - the dependencies of the artifacts are automatically obtained from Maven and used during the analysis so that the complete classpath is used

  • you’re not constrained to check the artifacts of the current project - in fact you could have a separate "check" module that would perform API checks completely separately from other modules in the project.

Updating Version In pom.xml

Goal details page: here

Revapi needs two artifacts to compare against each other to determine the API differences and therefore the required version changes. By default the new artifact is the project being built so the artifacts need to be actually produced prior to running revapi. This is usually done in the package phase, which is therefore run prior to any Revapi goal.

When updating the version, the plugin takes into consideration the configuration of Revapi as declared in the pom.xml but does not use certain extensions that would make some of the differences disappear (like the semver-ignore extension). This list of extensions is configurable using the disallowedExtensions configuration property, see the goal’s detail page for further info.

For a single-module project, updating the versions is very simple:

mvn revapi:update-versions

The version in pom.xml will be updated according to the API changes and the semantic versioning rules.

For multi-module project, one has more options. If each of the modules in the project is independently versioned, then the invocation is the same as for the single-module project, but if you version the child modules uniformly with the parent (i.e. you set autoVersionSubmodules to true when releasing using the maven release plugin), you should set the singleVersionForAllModules of revapi to true, too. Generally, autoVersionSubmodules and singleVersionForAllModules should be set to the same value.

mvn revapi:update-versions -Drevapi.singleVersionForAllModules=true

This will check the API differences in all the child modules and will determine the version of the whole based on the "biggest" change. I.e. if one child module breaks the API then the major version will be increased in all modules even though the rest of the child modules might not have changed at all.

Updating Versions In release.properties

Goal details page: here

This works identically to the update versions goal but instead of updating the version directly in the pom.xml files, it creates or updates the release.properties file. This will then be read by the maven release plugin during the release process.

Thus, running:

mvn revapi:update-release-properties && mvn release:prepare

will automatically set the release and development versions for you according to the semver versioning rules.