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.
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
docs for details.
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
newVersion parameters with similar meaning to the
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
you can configure Revapi maven plugin like this:
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
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 is the default value of
configuration parameter, so the above configuration will take effect).
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:
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.
|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:
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
true when releasing using the maven release plugin), you should
singleVersionForAllModules of revapi to
true, too. Generally,
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.
|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.
mvn revapi:update-release-properties && mvn release:prepare
will automatically set the release and development versions for you according to the semver versioning rules.