From 0165f0db9267011fcca1d986f9728943c39ae572 Mon Sep 17 00:00:00 2001
From: Max Rydahl Andersen <max@xam.dk>
Date: Fri, 7 Aug 2020 10:34:43 +0200
Subject: [PATCH] Add revapi as option during build

Initial setup of revapi to get API change reports.
Still ways to go in tuning it; but would like to have it included in master
now to make coming PR's simpler to apply/manage.

This adds a profile to run api check - it is not currently activated by default
but should be in the future when we have the defaults tuned in to not generate
unwarranted noise.

Also `revapi.skip` is default true, meaning even when the profile is active no api check
will be done on a module unless it defines `revapi.skip=true` in its properties.

Thus for now to even have it run you need enable the api-check profile *and* the property.
i.e. `mvn -Papi-check -Drevapi.skip=false`

If you want to run it for everything (ignoring revapi.skip do the following::
`mvn -Papi-check -Drevapi.skip=false -DskipTests verify`

If you want to see it detect changes in dependencies that quarkus exposes/uses add `-Drevapi.checkdeps=true`

When run you should get a `target/revapi-results/` in every module that are included in the check.

That folder will have a `.json` and `.adoc` file capturing detected API changes/issues.

If you want to tweak the format of the `.adoc` file you can change that in revapi/**/*.ftl
and do a `mvn install` to have changes picked up.
---
 build-parent/pom.xml                          | 137 ++++++++++++++++++
 independent-projects/revapi/pom.xml           |  38 +++++
 .../src/main/resources/META-INF/revapi.ftl    |  49 +++++++
 .../resources/revapi/revapi-configuration.xml |  31 ++++
 pom.xml                                       |   1 +
 5 files changed, 256 insertions(+)
 create mode 100644 independent-projects/revapi/pom.xml
 create mode 100644 independent-projects/revapi/src/main/resources/META-INF/revapi.ftl
 create mode 100644 independent-projects/revapi/src/main/resources/revapi/revapi-configuration.xml

diff --git a/build-parent/pom.xml b/build-parent/pom.xml
index 958acdaf4d988..358a33f24d135 100644
--- a/build-parent/pom.xml
+++ b/build-parent/pom.xml
@@ -100,6 +100,21 @@
 
         <boring-ssl.version>2.0.30.Final</boring-ssl.version>
 
+        <!-- revapi API check -->
+        <revapi-maven-plugin.version>0.12.1</revapi-maven-plugin.version>
+        <revapi-java-plugin.version>0.22.0</revapi-java-plugin.version>
+        <build-helper-plugin.version>1.9.1</build-helper-plugin.version>
+        <revapi-reporter-text.version>0.12.1</revapi-reporter-text.version>
+        <revapi-reporter-json.version>0.2.1</revapi-reporter-json.version>
+         <!-- Latest release to be used by api-compatibility-check to check backwards compatibility of the Quarkus API. -->
+        <revapi.oldVersion>1.6.0.Final</revapi.oldVersion>
+        <revapi.newVersion>${project.version}</revapi.newVersion>
+        <!-- severity Possible values: equivalent, nonBreaking, potentiallyBreaking, breaking -->
+        <revapi.reportSeverity>nonBreaking</revapi.reportSeverity>
+        <!-- Skip the API checks by default. Let the modules opt in. -->
+        <revapi.skip>true</revapi.skip>
+        <!-- By default don't check dependencies -->
+        <revapi.checkdeps>false</revapi.checkdeps>
     </properties>
 
     <dependencyManagement>
@@ -495,6 +510,16 @@
                         </dependency>
                     </dependencies>
                 </plugin>
+                <plugin>
+                    <groupId>org.codehaus.mojo</groupId>
+                    <artifactId>build-helper-maven-plugin</artifactId>
+                    <version>${build-helper-plugin.version}</version>
+                </plugin>
+                <plugin>
+                    <groupId>org.revapi</groupId>
+                    <artifactId>revapi-maven-plugin</artifactId>
+                    <version>${revapi-maven-plugin.version}</version>
+                </plugin>
             </plugins>
         </pluginManagement>
     </build>
@@ -818,5 +843,117 @@
                 </plugins>
             </build>
         </profile>
+
+        <profile>
+            <id>api-check</id>
+            <activation>
+                <activeByDefault>false</activeByDefault>
+            </activation>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>org.codehaus.mojo</groupId>
+                        <artifactId>build-helper-maven-plugin</artifactId>
+                        <executions>
+                            <execution>
+                                <id>parse-version</id>
+                                <goals>
+                                    <goal>parse-version</goal>
+                                </goals>
+                                <phase>validate</phase>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <plugin>
+                        <groupId>org.revapi</groupId>
+                        <artifactId>revapi-maven-plugin</artifactId>
+                        <dependencies>
+                            <dependency>
+                                <groupId>io.quarkus</groupId>
+                                <artifactId>quarkus-revapi-config</artifactId>
+                                <version>${project.version}</version>
+                            </dependency>
+                            <dependency>
+                                <groupId>org.revapi</groupId>
+                                <artifactId>revapi-java</artifactId>
+                                <version>${revapi-java-plugin.version}</version>
+                            </dependency>
+                            <dependency>
+                                <groupId>org.revapi</groupId>
+                                <artifactId>revapi-reporter-json</artifactId>
+                                <version>${revapi-reporter-json.version}</version>
+                            </dependency>
+                            <dependency>
+                                <groupId>org.revapi</groupId>
+                                <artifactId>revapi-reporter-text</artifactId>
+                                <version>${revapi-reporter-text.version}</version>
+                            </dependency>
+                        </dependencies>
+                        <configuration>
+                            <oldArtifacts>
+                                <artifact>${project.groupId}:${project.artifactId}:${revapi.oldVersion}</artifact>
+                            </oldArtifacts>
+                            <newArtifacts>
+                                <artifact>${project.groupId}:${project.artifactId}:${revapi.newVersion}</artifact>
+                            </newArtifacts>
+                            <!-- don't fail is false making it possible to have 
+                                revapi checks without requiring config files -->
+                            <failOnMissingConfigurationFiles>false</failOnMissingConfigurationFiles>
+                            <!-- Consider changes from the latest .Final version, 
+                                not from the latest non-snapshot. -->
+                            <versionFormat>\d+\.\d+\.\d+\.Final</versionFormat>
+                            <!-- By default revapi will check the oldArtifact 
+                                against the currently executed build -->
+                            <!-- <checkDependencies>false</checkDependencies> -->
+                            <analysisConfigurationFiles>
+                                <configurationFile>
+                                    <resource>revapi/revapi-configuration.xml</resource>
+                                </configurationFile>
+                                <configurationFile>
+                                    <path>api-changes.xml</path>
+                                    <roots>
+                                        <root>versions/v${parsedVersion.majorVersion}.${parsedVersion.minorVersion}.${parsedVersion.incrementalVersion}</root>
+                                    </roots>
+                                </configurationFile>
+                            </analysisConfigurationFiles>
+                            <!-- By default, revapi will only fail the build 
+                                 if there are potentially breaking or breaking changes. However, in the report 
+                                 we want even non breaking changes to be present. -->
+                            <reportSeverity>nonBreaking</reportSeverity>
+                            <failSeverity>potentiallyBreaking</failSeverity>
+                            <failBuildOnProblemsFound>true</failBuildOnProblemsFound>
+                            <checkDependencies>${revapi.checkdeps}</checkDependencies>
+                            <ignoreSuggestionsFormat>xml</ignoreSuggestionsFormat>
+                            <ignoreSuggestionsFile>${project.build.directory}/api-changes-suggestions.xml</ignoreSuggestionsFile>
+                            <expandProperties>true</expandProperties>
+                        </configuration>
+                        <!-- Running two executions is a workaround to make sure 
+                             we get a HTML report in case revapi finds some incompatible changes. The 
+                             "check" goal will simply fail the whole build before it could get to the 
+                             report. To make sure we always get a HTML report, the "report" goal needs 
+                             to be executed before the "check" goal. Once https://github.com/revapi/revapi/issues/11 
+                             is fixed it should be possible to use single execution. -->
+                        <executions>
+                            <execution>
+                                <id>api-check</id>
+                                <goals>
+                                    <goal>check</goal>
+                                </goals>
+                                <phase>verify</phase>
+                            </execution>
+                            <execution>
+                                <!-- report can be found in ${build.directory}/site/revapi-report.html -->
+                                <id>api-report</id>
+                                <goals>
+                                    <goal>report</goal>
+                                </goals>
+                                <phase>package</phase>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+
     </profiles>
 </project>
diff --git a/independent-projects/revapi/pom.xml b/independent-projects/revapi/pom.xml
new file mode 100644
index 0000000000000..a011f6a81837c
--- /dev/null
+++ b/independent-projects/revapi/pom.xml
@@ -0,0 +1,38 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.jboss</groupId>
+        <artifactId>jboss-parent</artifactId>
+        <version>36</version>
+    </parent>
+    
+    <groupId>io.quarkus</groupId>
+    <artifactId>quarkus-revapi-config</artifactId>
+    <name>Quarkus revapi configuration</name>
+    <version>999-SNAPSHOT</version>    
+    <description>Contains the configuration of the Revapi API checker and the list of the API changes 
+        in the Quarkus APIs.
+    </description>
+    <packaging>jar</packaging>
+
+    <properties>
+        <format.skip>true</format.skip>
+    </properties>
+
+    <build>
+        <plugins>
+            <!-- 
+            This is not deployed into a Maven repository. It is merely installed into the local Maven repository
+            during a local build.
+            -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-deploy-plugin</artifactId>
+                <configuration>
+                    <skip>true</skip>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+</project>
diff --git a/independent-projects/revapi/src/main/resources/META-INF/revapi.ftl b/independent-projects/revapi/src/main/resources/META-INF/revapi.ftl
new file mode 100644
index 0000000000000..cbf91b7cffb67
--- /dev/null
+++ b/independent-projects/revapi/src/main/resources/META-INF/revapi.ftl
@@ -0,0 +1,49 @@
+<#ftl strip_whitespace=true>
+<#if reports?has_content>
+# API Change analysis Results
+
+The summary of the API changes between artifacts <#list analysis.oldApi.archives as archive>`${archive.name}`<#sep>, </#list> and 
+<#list analysis.newApi.archives as archive>`${archive.name}`<#sep>, </#list>
+
+[cols="1,1,1,1,1", options="header"]
+.Changes
+|===
+|Code
+|Element
+|Classification
+|Description
+|Justification
+
+<#list reports as report>
+
+<#list report.differences as diff>
+
+|${diff.code}
+|<#if report.newElement??>*${report.newElement}*</#if>
+<#if report.oldElement??>*${report.oldElement}*</#if>
+<#if diff.attachments['exampleUseChainInNewApi']??>
+  Example use chain in new api:
+<#list diff.attachments['exampleUseChainInNewApi']?split(" <- ") as e>
+  <-${e}
+</#list>
+</#if>
+<#if diff.attachments['exampleUseChainInOldApi']?? && diff.attachments['exampleUseChainInNewApi']! != diff.attachments['exampleUseChainInOldApi']>
+  Example use chain in old api:
+<#list diff.attachments['exampleUseChainInOldApi']?split(" <- ") as e>
+  <-${e}
+</#list>
+</#if>
+
+<#list diff.attachments?keys as key>
+<#if !['newArchive', 'newArchiveRole', 'oldArchive', 'oldArchiveRole','package','classQualifiedName','classSimpleName','elementKind','exception','methodName','exampleUseChainInNewApi','exampleUseChainInOldApi','fieldName']?seq_contains(key)>
+  ${key} = ${diff.attachments[key]}
+</#if>
+</#list>
+|<#list diff.classification?keys as compat><#if diff.classification?api.get(compat) != "NON_BREAKING">  ${compat?capitalize}: ${diff.classification?api.get(compat)?capitalize?replace("_","")}${'\n'}</#if></#list>
+|${diff.description}
+|${diff.justification!""}
+
+</#list>
+</#list>
+|===
+</#if>
\ No newline at end of file
diff --git a/independent-projects/revapi/src/main/resources/revapi/revapi-configuration.xml b/independent-projects/revapi/src/main/resources/revapi/revapi-configuration.xml
new file mode 100644
index 0000000000000..8d94f2bf2aa68
--- /dev/null
+++ b/independent-projects/revapi/src/main/resources/revapi/revapi-configuration.xml
@@ -0,0 +1,31 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!-- The basic configuration for Revapi API checks in all modules that have API checks enabled. -->
+<analysisConfiguration>
+  <revapi.java>
+    <missing-classes>
+      <behavior>error</behavior>
+      <ignoreMissingAnnotations>true</ignoreMissingAnnotations>
+    </missing-classes>
+    <filter>
+      <packages>
+        <regex>true</regex>
+        <exclude><item>javax\..*</item></exclude>
+      </packages>
+    </filter>
+  </revapi.java>
+    <!-- <revapi.reporter.text id="stdout">
+      <output>out</output>
+      <template>revapi.ftl</template>
+    </revapi.reporter.text>  -->
+    <revapi.reporter.text>
+      <minSeverity>NON_BREAKING</minSeverity>
+      <output>${project.build.directory}/revapi-results/revapi-breakages.adoc</output>
+      <template>revapi.ftl</template>
+    </revapi.reporter.text>
+    <revapi.reporter.json>
+        <minSeverity>NON_BREAKING</minSeverity>
+        <output>${project.build.directory}/revapi-results/revapi-breakages.json</output>
+        <indent>true</indent>
+        <keepEmptyFile>true</keepEmptyFile>
+      </revapi.reporter.json>
+</analysisConfiguration>
diff --git a/pom.xml b/pom.xml
index d795d4614b791..0870083069602 100644
--- a/pom.xml
+++ b/pom.xml
@@ -44,6 +44,7 @@
 
         <!-- External projects -->
         <module>independent-projects/ide-config</module>
+        <module>independent-projects/revapi</module>
         <module>independent-projects/arc</module>
         <module>independent-projects/bootstrap</module>
         <module>independent-projects/qute</module>