From 68e2644852cb8a20a9b430435acf8de2fdf839d3 Mon Sep 17 00:00:00 2001
From: Gregory Oschwald <goschwald@maxmind.com>
Date: Fri, 9 Jan 2026 15:38:12 -0800
Subject: [PATCH] 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>
---
 .github/workflows/api-compat.yml | 19 ++++++++++++++
 pom.xml                          | 44 ++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+)
 create mode 100644 .github/workflows/api-compat.yml

diff --git a/.github/workflows/api-compat.yml b/.github/workflows/api-compat.yml
new file mode 100644
index 00000000..559e473e
--- /dev/null
+++ b/.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
diff --git a/pom.xml b/pom.xml
index 3a516045..4fc2c3f2 100644
--- a/pom.xml
+++ b/pom.xml
@@ -305,4 +305,48 @@
             <url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
         </repository>
     </distributionManagement>
+
+    <profiles>
+        <profile>
+            <id>api-compat</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>com.github.siom79.japicmp</groupId>
+                        <artifactId>japicmp-maven-plugin</artifactId>
+                        <version>0.25.1</version>
+                        <configuration>
+                            <oldVersion>
+                                <dependency>
+                                    <groupId>${project.groupId}</groupId>
+                                    <artifactId>${project.artifactId}</artifactId>
+                                    <version>RELEASE</version>
+                                    <type>jar</type>
+                                </dependency>
+                            </oldVersion>
+                            <newVersion>
+                                <file>
+                                    <path>${project.build.directory}/${project.artifactId}-${project.version}.jar</path>
+                                </file>
+                            </newVersion>
+                            <parameter>
+                                <accessModifier>public</accessModifier>
+                                <breakBuildBasedOnSemanticVersioning>true</breakBuildBasedOnSemanticVersioning>
+                                <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>