googleapis · vverman · Apr 13, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
@@ -0,0 +1,67 @@
+---
+name: java-development
+description: General guidance on Java development practices, building, testing, and style in the monorepo. Use this skill when working on Java code across the repository.
+---
+
+# Java Development Guide
+
+This skill provides general guidelines for Java development inside the monorepo. It covers building, formatting, testing, and style conventions to ensure consistency across modules.
+
+## Workflow
+
+### 1. Building the Project
+
+The repository uses Maven as its primary build system.
+
+*   **Build All Modules**: To build all modules from the root of the repository, run:
+    ```bash
+    mvn install -T 1C -P quick-build
+    ```
+    > [!TIP]
+    > Use `-T 1C` to build modules in parallel (one thread per CPU core) and `-P quick-build` to skip unnecessary plugins for faster builds.
+*   **Build a Specific Module**: You can also run Maven commands within a specific module directory (e.g., `java-bigquery`) to build only that module.
+
+### 2. Code Formatting
+
+Code formatting is enforced using the `fmt-maven-plugin`.
+
+*   **Check Formatting**: To check for formatting issues without modifying files, run:
+    ```bash
+    mvn fmt:check -T 1C
+    ```
+*   **Apply Formatting**: To automatically format the code according to the project style, run:
+    ```bash
+    mvn fmt:format -T 1C
+    ```
+    > [!TIP]
+    > To save time, run `mvn fmt:format` within the specific module directory you are working on, rather than at the root.
+    > [!NOTE]
+    > Always run `mvn fmt:format` before committing changes to avoid build failures due to formatting.
+
+### 3. Testing Strategy
+
+*   **Unit Tests**: Traditional unit tests should be added for individual classes and methods. Run them using:
+    ```bash
+    mvn test -T 1C
+    ```
+*   **Integration Tests**: Many modules have integration tests that run against live services or emulators. These may require specific profiles or environment variables. Refer to the specific module's README for details.
+
+### 4. Style Guide
+
+Follow these general rules to maintain code quality and consistency:
+
+1.  **Minimize Visibility**: Default to the most restrictive access level possible. Avoid using `public` unless the class or method is intended to be part of the public API.
+2.  Avoid Fully Qualified Names: Use imports to keep class names short and readable, rather than using fully qualified names in the code.
+3.  **Avoid Obsolete APIs**: Do not call methods marked with `@ObsoleteApi` or `@Deprecated` unless there are no viable alternatives.
+4.  **Clean Diffs**: Avoid unnecessary formatting changes or whitespace modifications to keep diffs clean and easy to review.
+
+### 5. Dependency Management
+
+*   **Version Bumps**: Try not to bump any external dependency versions unless there is a known security vulnerability (CVE) or a critical bug fix.
+*   **New Dependencies**: Avoid introducing new external dependencies. If a new dependency is required, provide a strong justification in the pull request.
+*   **Standard Library First**: Prefer to use features from the Java standard library, followed by existing dependencies in the project (preferably Google-managed dependencies).
+
+### 6. Contribution Guidelines
+
+*   **Commit Messages**: Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Include the module as the scope (e.g., `feat(spanner): ...`, `fix(bigquery): ...`).
+*   **Pull Requests**: All code changes must be submitted via a pull request and require review. Ensure you pull the latest changes from `main` and resolve any conflicts before submitting.
@@ -31,7 +31,7 @@ jobs:
       ci: ${{ steps.filter.outputs.ci }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         # we want to run tests if source code is changed or the scripts
@@ -40,6 +40,14 @@ jobs:
           src:
             - '**/*.java'
             - '**/pom.xml'
+            - '!java-bigquery/**'
+            - '!java-bigquerystorage/**'
+            - '!java-datastore/**'
+            - '!java-logging-logback/**'
+            - '!java-logging/**'
+            - '!java-spanner/**'
+            - '!java-storage/**'
+            - '!google-auth-library-java/**'
           ci:
             - '.github/workflows/ci.yaml'
             - '.kokoro/**'
@@ -113,18 +121,58 @@ jobs:
     outputs:
       packages: ${{ steps.filter.outputs.changes }}
     steps:
-    - uses: dorny/paths-filter@v4
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
+        # For each library, run CI in split repos where there are changes in:
+        # 1. Changes inside the split repo's module
+        # 2. Java code changes in upstream modules: Auth Library and Sdk-Platform-Java
+        # 3. Upstream dependency version changes: Shared-Deps and Gapic-Generator-Pom-Parent
         filters: |
-          java-bigquery: java-bigquery/**
-          java-bigquerystorage: java-bigquerystorage/**
-          java-datastore: java-datastore/**
-          java-logging-logback: java-logging-logback/**
-          java-logging: java-logging/**
-          java-spanner: java-spanner/**
-          java-storage: java-storage/**
-          sdk-platform-java: sdk-platform-java/**
+          google-auth-library-java:
+            - 'google-auth-library-java/**'
+          java-bigquery:
+            - 'java-bigquery/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-bigquerystorage:
+            - 'java-bigquerystorage/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-datastore:
+            - 'java-datastore/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-logging-logback:
+            - 'java-logging-logback/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-logging:
+            - 'java-logging/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-spanner:
+            - 'java-spanner/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
+          java-storage:
+            - 'java-storage/**'
+            - 'google-auth-library-java/**/*.java'
+            - 'sdk-platform-java/**/*.java'
+            - 'sdk-platform-java/java-shared-dependencies/**/pom.xml'
+            - 'sdk-platform-java/gapic-generator-java-pom-parent/pom.xml'
   split-units:
     runs-on: ubuntu-latest
     needs: changes

@@ -1,28 +1,11 @@
-name: sdk-platform-java Create additional tags for each release
+name: Create additional tags for each release
 
 on:
   release:
     types: [published]
   workflow_dispatch:
-
-env:
-  BUILD_SUBDIR: sdk-platform-java
 jobs:
-  filter:
-    runs-on: ubuntu-latest
-    outputs:
-      library: ${{ steps.filter.outputs.library }}
-    steps:
-    - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
-      id: filter
-      with:
-        filters: |
-          library:
-            - 'sdk-platform-java/**'
   build:
-    needs: filter
-    if: ${{ needs.filter.outputs.library == 'true' }}
     runs-on: ubuntu-latest
     permissions:
       # Permission to create tag
@@ -32,7 +15,7 @@ jobs:
     - name: Checkout code
       uses: actions/checkout@v4
       with:
-        token: ${{ secrets.GITHUB_TOKEN }}
+        token: ${{ secrets.CLOUD_JAVA_BOT_TOKEN }}
     - name: Set up Git
       run: |
         git config --local user.email "action@github.com"

@@ -17,7 +17,7 @@ on:
   pull_request:
 name: generation diff
 env:
-  library_generation_image_tag: 2.70.0  # {x-version-update:gapic-generator-java:current}
+  library_generation_image_tag: 2.71.0  # {x-version-update:gapic-generator-java:current}
 jobs:
   root-pom:
     # root pom.xml does not have diff from generated one

@@ -28,7 +28,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -44,4 +44,4 @@ jobs:
         head_ref: ${{ github.head_ref }}
         token: ${{ secrets.CLOUD_JAVA_BOT_GITHUB_TOKEN }}
         force_regenerate_all: ${{ github.event.pull_request.head.ref == 'generate-libraries-main' }}
-        image_tag: 2.70.0  # {x-version-update:gapic-generator-java:current}
+        image_tag: 2.71.0  # {x-version-update:gapic-generator-java:current}
@@ -26,7 +26,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -11,7 +11,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -28,7 +28,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -13,7 +13,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -25,7 +25,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -25,7 +25,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -25,7 +25,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -25,7 +25,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -28,7 +28,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -26,7 +26,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -11,13 +11,14 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |
           library:
             - 'sdk-platform-java/**'
             - 'google-auth-library-java/**'
+            - '.github/workflows/ci.yaml'
   build:
     needs: filter
     if: ${{ needs.filter.outputs.library == 'true' }}
@@ -179,7 +180,13 @@ jobs:
         with:
           java-version: 17
           distribution: temurin
-      - name: Compile with Java 17 and run tests with Java 8
+      - name: Install all modules using Java 17
+        shell: bash
+        run: .kokoro/build.sh
+        env:
+          BUILD_SUBDIR: sdk-platform-java
+          JOB_TYPE: install
+      - name: Run tests with Java 8
         shell: bash
         run: |
           set -x
@@ -191,7 +198,7 @@ jobs:
               -Djvm="${JAVA8_HOME}/bin/java"
         working-directory: sdk-platform-java
       # The `envVarTest` profile runs tests that require an environment variable
-      - name: Compile with Java 17 and run tests with Java 8 (Env Var Tests)
+      - name: Run tests with Java 8 (Env Var Tests)
         shell: bash
         run: |
           set -x

@@ -23,7 +23,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |

@@ -17,12 +17,13 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |
           library:
             - 'sdk-platform-java/**'
+            - .kokoro/downstream-compatibility.sh
   downstream-compatibility:
     needs: filter
     if: ${{ needs.filter.outputs.library == 'true' }}

@@ -17,7 +17,7 @@ jobs:
       library: ${{ steps.filter.outputs.library }}
     steps:
     - uses: actions/checkout@v4
-    - uses: dorny/paths-filter@v3
+    - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
       id: filter
       with:
         filters: |
@@ -33,7 +33,7 @@ jobs:
         repo:
           - java-bigtable
           - java-firestore
-          - java-logging
+          - java-pubsub
     steps:
       - name: Checkout sdk-platform-java
         uses: actions/checkout@v3