Version number changes implications are not always clearly
identified. Can I be sure this new minor version didn't break the public
API? As a library writer, how to continuously validate I don't break
binary compatibility?
semantic-versioning is a Java library allowing to
validate (using bytecode inspection) if library version numbers follows
Semantic Versioning principles as defined by Semantic Versioning. It can check JAR files
or classes to identify changes between versions and validate if the new
version number is correct according to semver.
Semantic Versioning also provides an API for programmatically
validating your project's version number.
finalFile previousJar =...;finalFile currentJar =...;final Comparer comparer =newComparer(previousJar, currentJar,...,...);final Delta delta = comparer.diff();finalString compatibilityType =...;//Validates that computed and provided compatibility type are compatible.final Delta.CompatibilityType expectedCompatibilityType = Delta.CompatibilityType.valueOf(compatibilityType);final Delta.CompatibilityType detectedCompatibilityType = delta.computeCompatibilityType();if(detectedCompatibilityType.compareTo(expectedCompatibilityType)>0){//Not compatible.}//Provide version number for previous and current Jar files.final Version previous = Version.parse(...);final Version current = Version.parse(...);//Validates that current version number is valid based on semantic versioning principles.finalboolean compatible = delta.validate(previous, current);
CLI
This simple command line tool looks at Java JAR files and determine
API changes.
Built-in help
% java -jar semver.jar --help
Semantic Version validator.
Usage: semver [options]
Options:
--base-jar JAR The base jar.
--base-version VERSION Version of the base jar (given with --base-jar).
--check,-c Check the compatibility of two jars.
--diff,-d Show the differences between two jars.
--excludes EXCLUDE;... Semicolon separated list of full qualified class names
or partly qualified class names with wild cards
to be excluded.
--help,-h Show this help and exit.
--includes INCLUDE;... Semicolon separated list of full qualified class names
or partly qualified class names with wild cards
to be included.
--infer,-i Infer the version of the new jar based on the previous
jar.
--new-jar JAR The new jar.
--new-version VERSION Version of the new jar (given with --new-jar).
--validate,-v Validate that the versions of two jars fulfil the
semver specification.
Diff
Dump all changes between two JARs on standard output.
% java -jar semver.jar --diff --base-jar previousJar --new-jar current.jar
Class org.project.MyClass
Added Class
Class org.project.MyClass2
Added Method method1
Removed Field field1
Changed Field field2 removed: final
Excludes / Includes
In- or exclude classes for the validation by specifying a fully
qualified class name or using wild cards. There are two wild cards:
* and **. * is a wild card for an
arbitrary number of characters but at most one folder hierarchy.
** is a wild card for an arbitrary number of characters and
an arbitrary number of folder hierarchies.
The enforcer rule offers a rule for checking project's version
against a previously released artifact.
Checking a project's
compatibility
In order to check your project's compatibility, you must add the
enforcer rule as a dependency to the maven-enforcer-plugin and then
configure the maven-enforcer-plugin to run the rule:
Once you have configured your project, maven-enforcer will be able to
throw a build error if current version is not backward compatible with
last released one.
You can force strict checking (i.e. compatibility type must exactly
match specified one):
In order to check your project's version, you must add the enforcer
rule as a dependency to the maven-enforcer-plugin and then configure the
maven-enforcer-plugin to run the rule:
