From 6d9c3566b71900c54644a9f71ce028696ee5d4bd Mon Sep 17 00:00:00 2001
From: Marcono1234 <Marcono1234@users.noreply.github.com>
Date: Thu, 6 Jul 2023 19:04:36 +0200
Subject: [PATCH] Document minimum Android API level and add workflow to check
 compatibility (#2431)

---
 .../workflows/check-android-compatibility.yml | 29 +++++++++++++++++++
 .github/workflows/check-api-compatibility.yml |  2 ++
 README.md                                     |  7 +++++
 gson/pom.xml                                  |  1 +
 metrics/pom.xml                               |  8 +++++
 pom.xml                                       | 27 +++++++++++++++++
 shrinker-test/pom.xml                         |  8 +++++
 7 files changed, 82 insertions(+)
 create mode 100644 .github/workflows/check-android-compatibility.yml

diff --git a/.github/workflows/check-android-compatibility.yml b/.github/workflows/check-android-compatibility.yml
new file mode 100644
index 00000000..e71956fa
--- /dev/null
+++ b/.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
diff --git a/.github/workflows/check-api-compatibility.yml b/.github/workflows/check-api-compatibility.yml
index a4465764..79a793f5 100644
--- a/.github/workflows/check-api-compatibility.yml
+++ b/.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
diff --git a/README.md b/README.md
index 04eb1c94..7418a27a 100644
--- a/README.md
+++ b/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
diff --git a/gson/pom.xml b/gson/pom.xml
index 4cb7757d..0e120d3e 100644
--- a/gson/pom.xml
+++ b/gson/pom.xml
@@ -276,6 +276,7 @@
       </plugin>
     </plugins>
   </build>
+
   <profiles>
     <profile>
       <id>JDK17</id>
diff --git a/metrics/pom.xml b/metrics/pom.xml
index 82f2c8ea..82098745 100644
--- a/metrics/pom.xml
+++ b/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>
diff --git a/pom.xml b/pom.xml
index 34df6c4c..9ba8f039 100644
--- a/pom.xml
+++ b/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>
diff --git a/shrinker-test/pom.xml b/shrinker-test/pom.xml
index 7c6a4bac..e72d26e6 100644
--- a/shrinker-test/pom.xml
+++ b/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>