Add API compatibility checking with japicmp

This adds a GitHub Actions workflow that runs on PRs to detect breaking
changes in the public API. The check uses japicmp with semantic versioning
support, so it will only fail if breaking changes are detected without a
major version bump.

ENG-3367

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: oschwald

.github/workflows/api-compat.yml

@@ -0,0 +1,19 @@
+name: API Compatibility Check
+on:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  api-compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-java@f2beeb24e141e01a676f977032f5a29d81c9e27e # v5.1.0
+        with:
+          distribution: zulu
+          java-version: 17
+          cache: maven
+      - name: Check API Compatibility
+        run: mvn verify -P api-compat -DskipTests -Dgpg.skip=true

dev-bin/release.sh

@@ -134,6 +134,9 @@ mvn versions:set -DnewVersion="$version"
 perl -pi -e "s/(?<=<version>)[^<]*/$version/" README.md
 perl -pi -e "s/(?<=com\.maxmind\.minfraud\:minfraud\:)\d+\.\d+\.\d+([\w\-]+)?/$version/" README.md
 
+# Update japicmp.baselineVersion for API compatibility checking
+perl -pi -e "s/(<japicmp\.baselineVersion>)[^<]*(<\/japicmp\.baselineVersion>)/\${1}$version\${2}/" pom.xml
+
 cat README.md >>$page
 
 git diff

pom.xml

@@ -277,6 +277,8 @@
 
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <!-- Baseline version for API compatibility checking. Update after each release. -->
+        <japicmp.baselineVersion>4.0.0</japicmp.baselineVersion>
     </properties>
 
     <reporting>
@@ -305,4 +307,68 @@
             <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
         </repository>
     </distributionManagement>
+
+    <profiles>
+        <profile>
+            <id>api-compat</id>
+            <build>
+                <plugins>
+                    <!-- Download baseline JAR directly from Maven Central for API comparison -->
+                    <plugin>
+                        <groupId>org.apache.maven.plugins</groupId>
+                        <artifactId>maven-antrun-plugin</artifactId>
+                        <version>3.1.0</version>
+                        <executions>
+                            <execution>
+                                <id>download-baseline</id>
+                                <phase>package</phase>
+                                <goals>
+                                    <goal>run</goal>
+                                </goals>
+                                <configuration>
+                                    <target>
+                                        <mkdir dir="${project.build.directory}/japicmp"/>
+                                        <get src="https://repo1.maven.org/maven2/com/maxmind/minfraud/minfraud/${japicmp.baselineVersion}/minfraud-${japicmp.baselineVersion}.jar"
+                                             dest="${project.build.directory}/japicmp/baseline.jar"
+                                             skipexisting="false"/>
+                                    </target>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                    <plugin>
+                        <groupId>com.github.siom79.japicmp</groupId>
+                        <artifactId>japicmp-maven-plugin</artifactId>
+                        <version>0.25.1</version>
+                        <configuration>
+                            <oldVersion>
+                                <file>
+                                    <path>${project.build.directory}/japicmp/baseline.jar</path>
+                                </file>
+                            </oldVersion>
+                            <newVersion>
+                                <file>
+                                    <path>${project.build.directory}/${project.artifactId}-${project.version}.jar</path>
+                                </file>
+                            </newVersion>
+                            <parameter>
+                                <accessModifier>public</accessModifier>
+                                <breakBuildOnBinaryIncompatibleModifications>true</breakBuildOnBinaryIncompatibleModifications>
+                                <onlyBinaryIncompatible>false</onlyBinaryIncompatible>
+                                <onlyModified>true</onlyModified>
+                            </parameter>
+                        </configuration>
+                        <executions>
+                            <execution>
+                                <phase>verify</phase>
+                                <goals>
+                                    <goal>cmp</goal>
+                                </goals>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
 </project>