ci: Use Linkage Checker to test Binary Compatibility

.github/workflows/downstream_protobuf_compatibility_check_nightly.yaml

@@ -43,12 +43,17 @@ jobs:
         # which values to use and would resolve to ''.
         protobuf-version: ${{ fromJSON(format('[{0}]', inputs.protobuf_runtime_versions || '"3.25.5","4.28.3"')) }}
     steps:
-      - uses: actions/checkout@v4
+      - name: Checkout sdk-platform-java repo
+        uses: actions/checkout@v4
       - uses: actions/setup-java@v4
         with:
-          java-version: 17
+          # Use Java 11 for this as Linkage Checker is only compatible with Java 11 or below
+          java-version: 11
           distribution: temurin
       - name: Print Protobuf-Java testing version
         run: echo "Testing with Protobuf-Java v${{ matrix.protobuf-version }}"
       - name: Perform downstream source compatibility testing
-        run: REPOS_UNDER_TEST="${{ matrix.repo }}" PROTOBUF_RUNTIME_VERSION="${{ matrix.protobuf-version}}" ./.kokoro/nightly/downstream-protobuf-source-compatibility.sh
+        run: REPOS_UNDER_TEST="${{ matrix.repo }}" PROTOBUF_RUNTIME_VERSION="${{ matrix.protobuf-version }}" ./.kokoro/nightly/downstream-protobuf-source-compatibility.sh
+      - name: Perform downstream binary compatibility testing
+        run: REPOS_UNDER_TEST="${{ matrix.repo }}" PROTOBUF_RUNTIME_VERSION="${{ matrix.protobuf-version }}" ./.kokoro/nightly/downstream-protobuf-binary-compatibility.sh
+

.kokoro/nightly/common.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Checks that the protobuf compatibility scripts provide non-empty input
+function validate_protobuf_compatibility_script_inputs {
+  # Comma-delimited list of repos to test
+  if [ -z "${REPOS_UNDER_TEST}" ]; then
+    echo "REPOS_UNDER_TEST Env Var must be set. This script expects a"
+    echo "comma-delimited list: i.e REPOS_UNDER_TEST=\"java-bigtable,java-bigquery\""
+    exit 1
+  fi
+
+  # A single version of Protobuf-Java runtime to test
+  if [ -z "${PROTOBUF_RUNTIME_VERSION}" ]; then
+    echo "PROTOBUF_RUNTIME_VERSION Env Var must be set. This script expects a single "
+    echo "Protobuf-Java runtime version i.e. PROTOBUF_RUNTIME_VERSION=\"4.28.3\""
+    exit 1
+  fi
+}

.kokoro/nightly/downstream-protobuf-binary-compatibility.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -eo pipefail
+
+scriptDir=$(realpath "$(dirname "${BASH_SOURCE[0]}")")
+source "${scriptDir}/common.sh"
+
+validate_protobuf_compatibility_script_inputs
+
+# Create two mappings of possible API names (Key: Maven Artifact ID Prefix, Value: Maven Group ID)
+# for the libraries that should be tested.
+# 1. These are special handwritten libraries in google-cloud-java that should be tested
+declare -A monorepo_handwritten_libraries
+monorepo_handwritten_libraries["grafeas"]="io.grafeas"
+monorepo_handwritten_libraries["google-cloud-vertexai"]="com.google.cloud"
+monorepo_handwritten_libraries["google-cloud-resourcemanager"]="com.google.cloud"
+monorepo_handwritten_libraries["google-cloud-translate"]="com.google.cloud"
+# Test a few grpc-* modules as gRPC-Java controls their Protobuf version and may generate code using
+# a different version of Protobuf. Not all grpc-* modules are tested as this may build a massive list
+# of artifacts. Maven has a limit on the number of arguments it can take (google-cloud-java surpasses that)
+monorepo_handwritten_libraries["grpc-google-cloud-vertexai"]="com.google.api.grpc"
+monorepo_handwritten_libraries["grpc-google-cloud-resourcemanager"]="com.google.api.grpc"
+monorepo_handwritten_libraries["grpc-google-cloud-translate"]="com.google.api.grpc"
+
+# 2. These are the mappings of all the downstream handwritten libraries' artifacts
+declare -A downstream_handwritten_libraries
+downstream_handwritten_libraries["google-cloud"]="com.google.cloud"
+downstream_handwritten_libraries["grpc-google-cloud"]="com.google.api.grpc"
+
+# Builds a string output to `artifact_list`. It contains a comma separate list of Maven GAV coordinates. Parses
+# the `versions.txt` file by searching for the matching artifact_id_prefix to get the corresponding version.
+function build_artifact_list() {
+  local -n api_maven_mapping=$1
+  for artifact_id_prefix in "${!api_maven_mapping[@]}"; do
+    group_id="${api_maven_mapping[${artifact_id_prefix}]}"
+
+    # Match all artifacts that start with the $artifact_id_prefix exclude any non-relevant modules.
+    repo_artifact_list=$(cat "versions.txt" | grep -E "^${artifact_id_prefix}" || true)
+
+    # Only proceed if there are matching elements
+    if [ -n "${repo_artifact_list}" ]; then
+      # Exclude any matches to BOM artifacts or emulators. The repo artifact list will look like:
+      # "com.google.cloud:google-cloud-accessapproval:2.60.0-SNAPSHOT,com.google.cloud:google-cloud-aiplatform:3.60.0-SNAPSHOT,"
+      repo_artifact_list=$(echo "${repo_artifact_list}" | grep -vE "(bom|emulator|google-cloud-java)" | awk -F: "{\$1=\"${group_id}:\"\$1; \$2=\"\"; print}" OFS=: | sed 's/::/:/' | tr '\n' ',')
+      # Remove the trailing comma after the last entry
+      repo_artifact_list=${repo_artifact_list%,}
+
+      # The first entry added is not separated with a comma. Avoids generating `,{ARTIFACT_LIST}`
+      if [ -z "${artifact_list}" ]; then
+        artifact_list="${repo_artifact_list}"
+      else
+        artifact_list="${artifact_list},${repo_artifact_list}"
+      fi
+    fi
+  done
+}
+
+# cloud-opensource-java contains the Linkage Checker tool
+git clone https://github.com/GoogleCloudPlatform/cloud-opensource-java.git
+pushd cloud-opensource-java
+mvn -B -ntp clean compile -T 1C
+# Linkage Checker tool resides in the /dependencies subfolder
+pushd dependencies
+
+for repo in ${REPOS_UNDER_TEST//,/ }; do # Split on comma
+  # Perform testing on main (with latest changes). Shallow copy as history is not important
+  git clone "https://github.com/googleapis/${repo}.git" --depth=1
+  pushd "${repo}"
+  # Install all repo modules to ~/.m2 (there can be multiple relevant artifacts to test i.e. core, admin, control)
+  mvn -B -ntp install -T 1C -DskipTests -Dclirr.skip -Denforcer.skip
+
+  artifact_list=""
+  if [ "${repo}" == "google-cloud-java" ]; then
+    build_artifact_list monorepo_handwritten_libraries
+  else
+    build_artifact_list downstream_handwritten_libraries
+  fi
+
+  # Linkage Checker /dependencies
+  popd
+
+  echo "Artifact List: ${artifact_list}"
+  # The `-s` argument filters the linkage check problems that stem from the artifact
+  if [ -n "${artifact_list}" ]; then
+    program_args="-r --artifacts ${artifact_list},com.google.protobuf:protobuf-java:${PROTOBUF_RUNTIME_VERSION},com.google.protobuf:protobuf-java-util:${PROTOBUF_RUNTIME_VERSION} -s ${artifact_list}"
+    echo "Running Linkage Checker on the repo's handwritten modules"
+    echo "Linkage Checker Program Arguments: ${program_args}"
+    mvn -B -ntp exec:java -Dexec.args="${program_args}" -P exec-linkage-checker
+  else
+    echo "Unable to find any matching artifacts to test in ${repo}"
+    exit 1
+  fi
+done
+popd
+popd

.kokoro/nightly/downstream-protobuf-source-compatibility.sh

@@ -15,19 +15,10 @@
 
 set -eo pipefail
 
-# Comma-delimited list of repos to test with the local java-shared-dependencies
-if [ -z "${REPOS_UNDER_TEST}" ]; then
-  echo "REPOS_UNDER_TEST must be set to run downstream-protobuf-source-compatibility.sh"
-  echo "Expects a comma-delimited list: i.e REPOS_UNDER_TEST=\"java-bigtable,java-bigquery\""
-  exit 1
-fi
+scriptDir=$(realpath "$(dirname "${BASH_SOURCE[0]}")")
+source "${scriptDir}/common.sh"
 
-# Version of Protobuf-Java runtime to compile with
-if [ -z "${PROTOBUF_RUNTIME_VERSION}" ]; then
-  echo "PROTOBUF_RUNTIME_VERSION must be set to run downstream-protobuf-source-compatibility.sh"
-  echo "Expects a single Protobuf-Java runtime version i.e. PROTOBUF_RUNTIME_VERSION=\"4.28.3\""
-  exit 1
-fi
+validate_protobuf_compatibility_script_inputs
 
 for repo in ${REPOS_UNDER_TEST//,/ }; do # Split on comma
   # Perform source-compatibility testing on main (latest changes)