From 7ce169519b1720ea03bea50383fd5f834fe115c9 Mon Sep 17 00:00:00 2001
From: Gregory Oschwald <goschwald@maxmind.com>
Date: Fri, 9 Jan 2026 15:38:10 -0800
Subject: [PATCH 1/2] 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 | 20 ++++++++++
 dev-bin/release.sh               |  3 ++
 pom.xml                          | 63 ++++++++++++++++++++++++++++++++
 3 files changed, 86 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..65c13f99
--- /dev/null
+++ b/.github/workflows/api-compat.yml
@@ -0,0 +1,20 @@
+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:
+          submodules: true
+          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/dev-bin/release.sh b/dev-bin/release.sh
index 65f7f62d..1052094b 100755
--- a/dev-bin/release.sh
+++ b/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\.geoip2\:geoip2\:)\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
diff --git a/pom.xml b/pom.xml
index b6926848..09807306 100644
--- a/pom.xml
+++ b/pom.xml
@@ -102,6 +102,8 @@
     </dependencies>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <!-- Baseline version for API compatibility checking. Update after each release. -->
+        <japicmp.baselineVersion>5.0.2</japicmp.baselineVersion>
     </properties>
     <build>
         <plugins>
@@ -304,5 +306,66 @@
                 </plugins>
             </build>
         </profile>
+        <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/geoip2/geoip2/${japicmp.baselineVersion}/geoip2-${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>

From e0f63cef3d71148e0b071a882c20d9c53887672a Mon Sep 17 00:00:00 2001
From: Gregory Oschwald <goschwald@maxmind.com>
Date: Mon, 12 Jan 2026 09:30:43 -0800
Subject: [PATCH 2/2] Intentially make a breaking change

---
 .../maxmind/geoip2/model/AnonymousPlusResponse.java    | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/src/main/java/com/maxmind/geoip2/model/AnonymousPlusResponse.java b/src/main/java/com/maxmind/geoip2/model/AnonymousPlusResponse.java
index 22ac498b..1763d35f 100644
--- a/src/main/java/com/maxmind/geoip2/model/AnonymousPlusResponse.java
+++ b/src/main/java/com/maxmind/geoip2/model/AnonymousPlusResponse.java
@@ -135,16 +135,6 @@ public AnonymousPlusResponse(
         );
     }
 
-    /**
-     * @return The IP address that the data in the model is for.
-     * @deprecated Use {@link #ipAddress()} instead. This method will be removed in 6.0.0.
-     */
-    @Deprecated(since = "5.0.0", forRemoval = true)
-    @JsonProperty("ip_address")
-    public String getIpAddress() {
-        return ipAddress().getHostAddress();
-    }
-
     /**
      * @return The network associated with the record. In particular, this is
      * the largest network where all the fields besides IP address have the