Document minimum Android API level and add workflow to check compatibility (#2431)

.github/workflows/check-android-compatibility.yml

@@ -0,0 +1,29 @@
+# For security reasons this is a separate GitHub workflow, see https://github.com/google/gson/issues/2429#issuecomment-1622522842
+# Once https://github.com/mojohaus/animal-sniffer/issues/252 or https://github.com/mojohaus/animal-sniffer/pull/253
+# are resolved, can consider adjusting pom.xml to include this as part of normal Maven build
+
+name: Check Android compatibility
+
+on: [push, pull_request]
+
+permissions:
+  contents: read #  to fetch code (actions/checkout)
+
+jobs:
+  check-android-compatibility:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up JDK 11
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '11'
+          cache: 'maven'
+
+      - name: Check Android compatibility
+        run: |
+          # Run 'test' phase because plugin normally expects to be executed after tests have been compiled
+          mvn --batch-mode --no-transfer-progress test animal-sniffer:check@check-android-compatibility -DskipTests

.github/workflows/check-api-compatibility.yml

@@ -1,3 +1,5 @@
+# This workflow makes sure that a pull request does not make any incompatible changes
+# to the public API of Gson
 name: Check API compatibility
 
 on: pull_request

README.md

@@ -55,6 +55,13 @@ When this module is present, Gson can use the `Unsafe` class to create instances
 However, care should be taken when relying on this. `Unsafe` is not available in all environments and its usage has some pitfalls,
 see [`GsonBuilder.disableJdkUnsafe()`](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/GsonBuilder.html#disableJdkUnsafe()).
 
+#### Minimum Android API level
+
+- Gson 2.11.0 and newer: API level 21
+- Gson 2.10.1 and older: API level 19
+
+Older Gson versions may also support lower API levels, however this has not been verified.
+
 ### Documentation
   * [API Javadoc](https://www.javadoc.io/doc/com.google.code.gson/gson): Documentation for the current release
   * [User guide](UserGuide.md): This guide contains examples on how to use Gson in your code

gson/pom.xml

@@ -276,6 +276,7 @@
       </plugin>
     </plugins>
   </build>
+
   <profiles>
     <profile>
       <id>JDK17</id>

metrics/pom.xml

@@ -68,6 +68,14 @@
             <skip>true</skip>
           </configuration>
         </plugin>
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>animal-sniffer-maven-plugin</artifactId>
+          <configuration>
+            <!-- This module is not supposed to be consumed as library, so no need to check used classes -->
+            <skip>true</skip>
+          </configuration>
+        </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-deploy-plugin</artifactId>

pom.xml

@@ -315,6 +315,33 @@
             </parameter>
           </configuration>
         </plugin>
+        <!-- Plugin for checking compatibility with Android API -->
+        <!-- Note: For now this is not part of a normal Maven build but instead executed only by a
+          GitHub workflow because the Animal Sniffer signature files use Java Serialization, so they
+          could in theory contain malicious data (in case we don't fully trust the author) -->
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>animal-sniffer-maven-plugin</artifactId>
+          <version>1.23</version>
+          <executions>
+            <execution>
+              <id>check-android-compatibility</id>
+              <goals>
+                <goal>check</goal>
+              </goals>
+              <configuration>
+                <signature>
+                  <!-- Note: In case Android compatibility impedes Gson development too much in the
+                    future, could consider switching to https://github.com/open-toast/gummy-bears
+                    which accounts for Android desugaring and might allow usage of more Java classes -->
+                  <groupId>net.sf.androidscents.signature</groupId>
+                  <artifactId>android-api-level-21</artifactId>
+                  <version>5.0.1_r2</version>
+                </signature>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
     </pluginManagement>
   </build>

shrinker-test/pom.xml

@@ -69,6 +69,14 @@
             <skip>true</skip>
           </configuration>
         </plugin>
+        <plugin>
+          <groupId>org.codehaus.mojo</groupId>
+          <artifactId>animal-sniffer-maven-plugin</artifactId>
+          <configuration>
+            <!-- This module is not supposed to be consumed as library, so no need to check used classes -->
+            <skip>true</skip>
+          </configuration>
+        </plugin>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-deploy-plugin</artifactId>