Reporting Improvements

After quite a long and relatively quiet period where Revapi received only bugfixes and small new enhancements, this release brings new improvements that touch the very way Revapi operates in the builds.

Also, as you might have noticed reading this, the site has been revamped and is now generated by Antora.i This means that your saved links generally don’t work anymore, the RSS feed is on another location, etc. I am sorry about this but this change was necessary to enable a versioned site. From now on, the documentation will also be available for the past releases, not just the latest one. This is in preparation for the 1.0 release (that is still some time in the future).

There were actually no bugs fixed in this release, only new features have been implemented:

  • #192 - the external configuration files or Revapi can now contain variable references that are correctly interpolated with values known in the Maven reactor.

  • Freemarker has been update to the latest version, 2.3.30, in the revapi-reporter-text extension.

  • failBuildOnProblemsFound and outputIgnoreSuggestions maven plugin properties are now logically independent.

  • #198 - The new ignoreSuggestionsFile option enables one to also store the ignore suggestion snippets in a file.

  • #197 - All found differences now contain 2 new attachments (aka matche parameters): oldArchiveRole and newArchiveRole - these indicate whether the old or new element come from the primary API (with value primary) or from the dependencies (with value supplementary).

  • #202 - revapi.ignore and revapi.reclassify extensions are now DEPRECATED in favor of the new revapi.differences that melds the two together and adds a couple of new features on top. This change is significant enough to have its own separate paragraph below.

  • #199 - revapi.reporter.json and revapi.reporter.text now have a new configuration property - keepEmptyFile (defaulting to true) which enables the report to not even create the report file when there are no reportable differences found.

  • #203 - This introduces the concept of difference criticality - a new way of determining whether to report the difference or break the build because of it. This again is discussed separately below.

  • #204 - This taught maven plugin to use the criticality instead of the difference severity as an indicator for failing the build.

Thanks go out to Simon Bernard for providing an FAQ entry about the slightly non-obvious circumstances where Revapi might complain about an external class exposed in the API, and especially to Max Andersen that sparked all of the cool ideas how to make the reporting and build breaking much more usable.

Reporting improvements

As mentioned above, this release introduces the revapi.differences extension and deprecates revapi.ignore and revapi.reclassify. The new extension keeps the functionality of the old two but brings about acouple of important new features that enable us to greatly improve reporting and difference handling.

Apart from ignoring (which really means removing) differences and reclassifying them, the new extension can also just set a justification on a difference or set its criticality. These two properties are then carried on the differences over to the reporters that can make use of them. This enables the long awaited feature of reporting the justifications for the differences in the report.

This new extension also enables the user to add new attachments (aka match parameters) to the differences. These attachments are then available for processing by other difference transformations or by reporters. You can for example use it to assign a JIRA reference to the API change, etc.

Probably the most important new feature of this extension though is the ability to ignore or modify the differences en-masse. The documentation shows an example how to use this to have a single external configuration file with all the differences (as is the usual practice in the community) and use this configuration to both break the build at build time and generate a full change report with justifications during the report generation. See more in the docs.

Criticality

Criticality is Revapi’s new way of determining the impact of a difference. It can assume configurable values but by default it can be the following: allowed, documented, hightlight, error. These may look a bit strange at first, but IMHO they capture quite well how the API changes are usually dealt with. The authors either allow certain types of changes in their APIs or they document the API changes, some API changes might be even more important as to be highlighted in the release announcements, and finally some API changes are just not allowed and are considered errors.

Criticality is a new property of a difference and is assigned during the difference transformation phase. If no difference transform assigns the criticality to a difference, the criticality is automatically assigned to it using a mapping between a difference severity and criticality. As such, when the differences are finally processed by the reporters, the reporters always know how "critical" each difference is.