Enforcing Semantic Versioning

Off the cuff most developers will say yes.

And indeed it is compatible API.

However, is it NOT ABI compatible.

Java inlines the constant in compiled code.

This means old code that is not recompiled will continue to function with the OLD value, not the new value.

Analyzing an API for backwards compatibility is not a trivial task.

It often requires developers skilled in the fine grain minutiae of the language.

And even then mistakes do happen.

If only we had a way to enforce semantic versioning rules on our API’s.

Force the library to change when needed, don’t allow developers to lieEnsure all backwards compatibility rules are checked the same ways alwaysDo this quickly in a repeatable fashion and break the build if rules are brokenPhoto by Lex Photography from PexelsToolingIncorrect semantic versioning had become a chronic problem at our office.

We needed an automated solution to integrate into our workflow.

We are a Java shop that utilizes Maven as our build tool.

So I went looking for a Maven plugin we could integrate into our build process.

I was surprised to when I didn’t find any.

I did find some command line tools:JAPICCEclipse (UI Only)PkgDiffClirrWhile Clirr offered a maven plugin it also seems to be inactive and hasn’t be updated since 2005.

PkgDiff is a more general tool and doesn’t show changes in classes nor does it determine if changes are backwards compatible.

Eclipse actually has a Java based tool for versioning OSGi bundles in RCP application.

It works great from within Eclipse but is nearly impossible to use outside of it.

Especially on single libraries.

JAPICC — Java API Compliance Checker is a perl script that is relatively active, with support for up to Java 9.

It produces a very easy to read report of both API and ABI compatibility.

The only real draw back is its written in perl, and there is no maven plugin available.

Until now…Photo by Somchai Kongkamsri from PexelsHow to useIntroducing the Maven JAPICC Plugin.

This plugin allows you to enforce semantic versioning rules on your java project.

Prerequisites:Previous artifacts must be available through a Maven RepositoryBuild environments must have Perl installedSetup you pom to enable the plugin:<plugin> <groupId>io.



japicc</groupId> <artifactId>japicc-plugin</artifactId> <version>1.


1</version> <executions> <execution> <goals> <goal>check</goal> </goals> <phase>verify</phase> </execution> </executions></plugin>The plugin will try to find previous build artifacts within the same major series.

For example, if you are developing version 2.


3-SNAPSHOT then the plugin will check against 2.


2 or whatever version it can find in the Maven repo.

This could mean version 2.


1 or 2.



If it can’t find a previous version it will assume it is the first in a series and skip execution.

By default, the plugin essentially ignores the micro version number and just tries to find the latest one.

For example, if you set the version to 2.


5-SNAPSHOT and your last release artifact was 2.


2 then the plugin will compare the current build jar against version 2.



How it worksThe maven plugin contains a copy of the original JAPICC Perl script.

When the plugin is invoked it will:Download the previous release artifact to your local maven repositoryCompare this against the built artifact in the target directoryThe plugin assumes perl is installed in the typical location of /usr/bin/perl.

This can be changed in the configuration.

You DO NOT need the JAPICC installed.

The plugin will “install” the tool and all associated files into a temporary location.

Depending on the return code of the perl script the plugin will either fail the build or let it pass.

If the script fails, the plugin will output the location of the report and fail the build.

Here is what a failed report looks like:Next StepsIt would be great to translate the perl script into Java to remove the dependency on Perl.

Checkout the plugin source at:efenglu/japicc-pluginA Maven plugin that enforces Java Semantic Versioning – efenglu/japicc-plugingithub.

com.. More details

Leave a Reply