[core] Adopt JApiCmp to enforce control over API changes

[jsotuyod]

The library (also available as a stand alone tool and a Maven plugin) checks the binary differences between 2 JARs.

This can allow us to enforce compliance with semantic versioning.

https://github.com/siom79/japicmp

[oowekyala]

There's also a sonarqube plugin, maybe that could be nice to have feedback on PRs.

In any case I think this would be really useful on the Maven build. The setup doesn't appear terribly complicated, I could try that shortly.

[adangel]

There is also https://revapi.org/ as an alternative.

[adangel]

I've tried out now both japicmp and revapi (actually on the current master branch).

• japicmp: https://github.com/adangel/scratchpad/tree/master/japicmp
  • Sample: https://chunk.pmd-code.org/pmd/d5db0e25-67d6-43b9-a20c-fab3639f1b4b/index.html
• revapi: https://github.com/adangel/scratchpad/tree/master/revapi

japicmp is easier to use (hence I could easily compare older versions), revapi looks more sophisticated.

One incompatibility, that revapi found on master (6.30.0-SNAPSHOT <-> 6.29.0) are these two changes:

pmd/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/DocumentNode.java

Line 106 in 9bda5b3

public Node getUnderlyingNode() {

pmd/pmd-core/src/main/java/net/sourceforge/pmd/lang/ast/xpath/saxon/ElementNode.java

Line 98 in 9bda5b3

public Node getUnderlyingNode() {

With #2872 we changed the return type from "Object" to "Node". This is Method Return Type Changed Covariantly which apparently is a binary incompatibility. Both classes however are annotated with @InternalApi. Is this Ok? I've configured revapi to ignore all changes, if the classes are annotated that way... Is this correct on 6.x?

Next steps:

• let revapi compare older versions and create some reports
• test with pmd7 - here we need to compare against the latest 6.x version... and since we have a major version change, no incompatibility should be detected.

FYI @oowekyala

[adangel]

Note: There is now also https://github.com/alien-tools/breakbot, see https://github.com/breakbot-playground/pmd/pull/2/checks for a sample report