feat: Merge ehsann/new-types into main and resolve conflicts

Author: wu-hui

.agents/skills/verify-local-changes/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: Verify Local Changes
+description: Verifies local Java SDK changes.
+---
+
+# Verify Local Changes
+
+This skill documents how to verify local code changes for the Java Firestore SDK. This should be run **every time** you complete a fix or feature and are prepared to push a pull request.
+
+## Prerequisites
+
+Ensure you have Maven installed and are in the `java-firestore` directory before running commands.
+
+---
+
+## Step 0: Format the Code
+
+Run the formatter to ensure formatting checks pass:
+
+```bash
+mvn com.spotify.fmt:fmt-maven-plugin:format
+```
+
+---
+
+## Step 1: Unit Testing (Isolated then Suite)
+
+1.  **Identify modified unit tests** in your changes.
+2.  **Run specific units only** to test isolated logic regressions:
+    ```bash
+    mvn test -Dtest=MyUnitTest#testMethod
+    ```
+3.  **Run the entire unit test suite** that contains those modified tests if the isolated unit tests pass:
+    ```bash
+    mvn test -Dtest=MyUnitTest
+    ```
+
+---
+
+## Step 2: Integration Testing (Isolated then Suite)
+
+### 💡 Integration Test Nuances (from `ITBaseTest.java`)
+
+When running integration tests, configure your execution using properties or environment variables:
+
+-   **`FIRESTORE_EDITION`**: 
+    -   `standard` (Default)
+    -   `enterprise`
+    -   *Note*: **Pipelines can only be run against `enterprise` editions**, while standard Queries run on both.
+-   **`FIRESTORE_DATABASE_ID`**:
+    -   Enterprise editions usually require a named database (often `enterprise`). Adjust this flag if pointing to specific instances.
+-   **`FIRESTORE_TARGET_BACKEND`**:
+    -   `PROD` (Default)
+    -   `QA` (points to standard sandboxes)
+    -   `NIGHTLY` (points to `test-firestore.sandbox.googleapis.com:443`)
+    -   `EMULATOR` (points to `localhost:8080`)
+
+1.  **Identify modified integration tests** (usually Starting in `IT`).
+2.  **Run specific integration tests only** (isolated checks run quicker):
+    ```bash
+    mvn verify -Penable-integration-tests -DFIRESTORE_EDITION=enterprise -DFIRESTORE_DATABASE_ID=enterprise -Dtest=ITTest#testMethod -Dclirr.skip=true -Denforcer.skip=true -fae
+    ```
+3.  **Run the entire integration test suite** for the modified class if isolation tests pass:
+    ```bash
+    mvn verify -Penable-integration-tests -DFIRESTORE_EDITION=enterprise -DFIRESTORE_DATABASE_ID=enterprise -Dtest=ITTest -Dclirr.skip=true -Denforcer.skip=true -fae
+    ```
+
+---
+
+## Step 3: Full Suite Regressions
+
+Run the full integration regression suite once you are confident subsets pass:
+
+```bash
+mvn verify -Penable-integration-tests -DFIRESTORE_EDITION=enterprise -DFIRESTORE_DATABASE_ID=enterprise -Dclirr.skip=true -Denforcer.skip=true -fae
+```
+
+---
+
+> [!TIP]
+> Use `-Dclirr.skip=true -Denforcer.skip=true` to speed up iterations where appropriate without leaking compliance checks.
+
+---
+
+## 🛠️ Troubleshooting & Source of Truth
+
+If you run into issues executing tests with the commands above, **consult the Kokoro configuration files** as the ultimate source of truth:
+
+-   **Presubmit configurations**: See `.kokoro/presubmit/integration.cfg` (or `integration-named-db.cfg`)
+-   **Nightly configurations**: See `.kokoro/nightly/integration.cfg` (or `integration-named-db.cfg`)
+-   **Build shell scripts**: See `.kokoro/build.sh`
+
+These files define the exact environment variables (e.g., specific endpoints or endpoints overrides) the CI server uses!

.github/.OwlBot-hermetic.yaml

@@ -5,6 +5,7 @@ deep-remove-regex:
 - "/google-cloud-firestore-admin/src"
 
 deep-preserve-regex:
+- "/.*google-.*/src/main/java/.*/stub/Version.java"
 - "/google-.*/src/test/java/com/google/cloud/.*/v.*/it/IT.*Test.java"
 - "/proto-google-cloud-firestore-v1/src/main/java/com/google/firestore/v1/DocumentPathName.java"
 - "/proto-google-cloud-firestore-v1/src/main/java/com/google/firestore/v1/AnyPathName.java"

.github/CODEOWNERS

@@ -4,23 +4,23 @@
 # For syntax help see:
 # https://help.github.com/en/github/creating-cloning-and-archiving-repositories/about-code-owners#codeowners-syntax
 
-# The @googleapis/api-firestore @googleapis/firestore-dpe is the default owner for changes in this repo
-*                       @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
+# The @googleapis/firestore-team is the default owner for changes in this repo
+*                       @googleapis/cloud-sdk-java-team @googleapis/firestore-team
 
 # for handwritten libraries, keep codeowner_team in .repo-metadata.json as owner
-**/*.java               @googleapis/api-firestore @googleapis/firestore-dpe
+**/*.java               @googleapis/cloud-sdk-java-team @googleapis/firestore-team
 
 # For generated Java code
-proto-*/                    @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
-grpc-*/                     @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
+proto-*/                    @googleapis/cloud-sdk-java-team @googleapis/firestore-team
+grpc-*/                     @googleapis/cloud-sdk-java-team @googleapis/firestore-team
 # Generated code pattern in google-cloud-firestore and google-cloud-firestore-admin
-**/*Client.java             @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
-**/*Settings.java           @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
-**/*ClientHttpJsonTest.java @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
-**/*ClientTest.java         @googleapis/yoshi-java @googleapis/api-firestore @googleapis/firestore-dpe
+**/*Client.java             @googleapis/cloud-sdk-java-team @googleapis/firestore-team
+**/*Settings.java           @googleapis/cloud-sdk-java-team @googleapis/firestore-team
+**/*ClientHttpJsonTest.java @googleapis/cloud-sdk-java-team @googleapis/firestore-team
+**/*ClientTest.java         @googleapis/cloud-sdk-java-team @googleapis/firestore-team
 
 # The java-samples-reviewers team is the default owner for samples changes
 samples/**/*.java       @googleapis/java-samples-reviewers
 
 # Generated snippets should not be owned by samples reviewers
-samples/snippets/generated/       @googleapis/yoshi-java
+samples/snippets/generated/       @googleapis/cloud-sdk-java-team

.github/release-please.yml

@@ -2,7 +2,10 @@ bumpMinorPreMajor: true
 handleGHRelease: true
 releaseType: java-yoshi
 branches:
+  - branch: java7
+  - branch: protobuf-4.x-rc
+    manifest: true
   - bumpMinorPreMajor: true
     handleGHRelease: true
-    releaseType: java-yoshi
-    branch: java7
+    releaseType: java-backport
+    branch: 3.36.x

.github/scripts/update_generation_config.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-set -e
+set -ex
 # This script should be run at the root of the repository.
 # This script is used to update googleapis_commitish, gapic_generator_version,
 # and libraries_bom_version in generation configuration at the time of running
@@ -15,8 +15,20 @@ set -e
 function get_latest_released_version() {
     local group_id=$1
     local artifact_id=$2
-    json_content=$(curl -s "https://search.maven.org/solrsearch/select?q=g:${group_id}+AND+a:${artifact_id}&core=gav&rows=500&wt=json")
-    latest=$(jq -r '.response.docs[] | select(.v | test("^[0-9]+(\\.[0-9]+)*$")) | .v' <<< "${json_content}" | sort -V | tail -n 1)
+    group_id_url_path="$(sed 's|\.|/|g' <<< "${group_id}")"
+    url="https://repo1.maven.org/maven2/${group_id_url_path}/${artifact_id}/maven-metadata.xml"
+    xml_content=$(curl -s --fail "${url}")
+    
+    # 1. Extract all version tags
+    # 2. Strip the XML tags to leave just the version numbers
+    # 3. Filter for strictly numbers.numbers.numbers (e.g., 2.54.0)
+    # 4. Sort by version (V) and take the last one (tail -n 1)
+    latest=$(echo "${xml_content}" \
+      | grep -oE '<version>[0-9]+\.[0-9]+\.[0-9]+</version>' \
+      | sed -E 's/<[^>]+>//g' \
+      | sort -V \
+      | tail -n 1)
+    
     if [[ -z "${latest}" ]]; then
         echo "The latest version of ${group_id}:${artifact_id} is empty."
         echo "The returned json from maven.org is invalid: ${json_content}"
@@ -36,13 +48,14 @@ function update_config() {
 }
 
 # Update an action to a new version in GitHub action.
+# the second argument must have the git tag (including "v").
 function update_action() {
     local key_word=$1
     local new_value=$2
     local file=$3
     echo "Update ${key_word} to ${new_value} in ${file}"
     # use a different delimiter because the key_word contains "/".
-    sed -i -e "s|${key_word}@v.*$|${key_word}@v${new_value}|" "${file}"
+    sed -i -e "s|${key_word}@[^ ]*$|${key_word}@${new_value}|" "${file}"
 }
 
 # The parameters of this script is:
@@ -131,12 +144,16 @@ rm -rf tmp-googleapis
 update_config "googleapis_commitish" "${latest_commit}" "${generation_config}"
 
 # Update gapic-generator-java version to the latest
-latest_version=$(get_latest_released_version "com.google.api" "gapic-generator-java")
-update_config "gapic_generator_version" "${latest_version}" "${generation_config}"
-
-# Update composite action version to latest gapic-generator-java version
-update_action "googleapis/sdk-platform-java/.github/scripts" \
-  "${latest_version}" \
+latest_gapic_generator_version=$(get_latest_released_version "com.google.api" "gapic-generator-java")
+update_config "gapic_generator_version" "${latest_gapic_generator_version}" "${generation_config}"
+
+# Update the GitHub Actions reference to the latest.
+# After the google-cloud-java monorepo migration of sdk-platform-java,
+# we cannot rely on the gapic-generator-java version tag. Let's use
+# the gapic-libraries-bom version
+latest_gapic_libraries_bom_version=$(get_latest_released_version "com.google.cloud" "gapic-libraries-bom")
+update_action "googleapis/google-cloud-java/sdk-platform-java/.github/scripts" \
+  "v${latest_gapic_libraries_bom_version}" \
   "${workflow}"
 
 # Update libraries-bom version to the latest

.github/sync-repo-settings.yaml

@@ -38,10 +38,30 @@ branchProtectionRules:
       - units (11)
       - 'Kokoro - Test: Integration'
       - cla/google
+  - pattern: 3.36.x
+    isAdminEnforced: true
+    requiredApprovingReviewCount: 1
+    requiresCodeOwnerReviews: true
+    requiresStrictStatusChecks: false
+    requiredStatusCheckContexts:
+      - dependencies (17)
+      - lint
+      - clirr
+      - units (8)
+      - units (11)
+      - 'Kokoro - Test: Integration'
+      - 'Kokoro - Test: Integration Against Named DB'
+      - cla/google
+      - 'Kokoro - Test: Java GraalVM Native Image A'
+      - 'Kokoro - Test: Java GraalVM Native Image B'
+      - 'Kokoro - Test: Java GraalVM Native Image C'
+      - javadoc
+      - library_generation
+      - unmanaged_dependency_check
 permissionRules:
   - team: yoshi-admins
     permission: admin
   - team: yoshi-java-admins
     permission: admin
-  - team: yoshi-java
+  - team: cloud-sdk-java-team
     permission: push

.github/workflows/ci.yaml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        java: [11, 17, 21]
+        java: [11, 17, 21, 25]
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-java@v4

.github/workflows/hermetic_library_generation.yaml

@@ -36,10 +36,10 @@ jobs:
       if: env.SHOULD_RUN == 'true'
       with:
         fetch-depth: 0
-        token: ${{ secrets.CLOUD_JAVA_BOT_TOKEN }}
-    - uses: googleapis/sdk-platform-java/.github/scripts@v2.56.2
+        token: ${{ secrets.CLOUD_JAVA_BOT_GITHUB_TOKEN }}
+    - uses: googleapis/google-cloud-java/sdk-platform-java/.github/scripts@v1.85.0
       if: env.SHOULD_RUN == 'true'
       with:
         base_ref: ${{ github.base_ref }}
         head_ref: ${{ github.head_ref }}
-        token: ${{ secrets.CLOUD_JAVA_BOT_TOKEN }}
+        token: ${{ secrets.CLOUD_JAVA_BOT_GITHUB_TOKEN }}

.github/workflows/renovate_config_check.yaml

@@ -4,6 +4,7 @@ on:
   pull_request:
     paths:
       - 'renovate.json'
+      - '.github/workflows/renovate_config_check.yaml'
 
 jobs:
   renovate_bot_config_validation:
@@ -18,8 +19,6 @@ jobs:
       with:
         node-version: '22'
 
-    - name: Install Renovate and Config Validator
+    - name: Run Renovate Config Validator
       run: |
-        npm install -g npm@latest
-        npm install --global renovate
-        renovate-config-validator
+        npx --package renovate@43.136.0 renovate-config-validator

.github/workflows/unmanaged-dependency-check.yaml

@@ -14,6 +14,6 @@ jobs:
       shell: bash
       run: .kokoro/build.sh
     - name: Unmanaged dependency check
-      uses: googleapis/sdk-platform-java/java-shared-dependencies/unmanaged-dependency-check@google-cloud-shared-dependencies/v3.46.2
+      uses: googleapis/google-cloud-java/sdk-platform-java/java-shared-dependencies/unmanaged-dependency-check@v1.85.0
       with:
         bom-path: google-cloud-firestore-bom/pom.xml