Skip to content

AGENTS.md

Latest commit

 

History

History
76 lines (63 loc) · 4.79 KB

AGENTS.md

File metadata and controls

76 lines (63 loc) · 4.79 KB
Raw

Agents Guide for google-cloud-java

1. Overview

This repository, google-cloud-java, contains the Java client libraries for Google Cloud Platform services, as well as core components in sdk-platform-java.

2. Project Structure

The repository is a monorepo containing both generated and handwritten libraries, as well as core platform components and parent POMs.

Core Modules

  • sdk-platform-java/: Contains foundational components for building client libraries.
    • Note: This directory has its own GEMINI.md file with detailed instructions specific to core development (GAPIC generator, GAX).
    • Includes gapic-generator-java (the generator) and gax-java (Google API Extensions).
  • google-auth-library-java/: The Google Auth Library for Java. This is a handwritten library used for authentication and credential management across all Google Cloud clients. It is a critical dependency for all client libraries.

Parent Modules and BOMs

  • google-cloud-pom-parent/: The top-level parent POM for all modules in the repository. It manages plugin versions and common configuration.
  • google-cloud-jar-parent/: The parent POM for all client library JAR modules in the repository. It inherits from google-cloud-pom-parent and manages shared dependencies.
  • gapic-libraries-bom/: The Bill of Materials (BOM) that manages versions of all client libraries to ensure compatibility when used together.
  • java-shared-dependencies/ (inside sdk-platform-java): Manages shared Maven dependencies for all Google Cloud Java client libraries to ensure consistency and avoid conflicts.

Client Libraries (java-<service>/)

Directories starting with java- are client libraries for specific Google Cloud services.

  • Generated Clients: The majority of these are automatically generated from service definitions (protos) using the GAPIC generator in sdk-platform-java.
  • Handwritten & Split Repositories: Some major libraries are either entirely handwritten or are maintained as "split repos" (they have their own standalone repositories in the googleapis GitHub organization but are also managed here). When working on these, be aware that changes may need to be synchronized with their respective split repos. Key examples include:

3. Getting Started

Prerequisites

  • Java 11+ (build targets Java 8 bytecode compatibility)
  • Maven 3.0+
  • Bazelisk (for integration tests in sdk-platform-java)

Building the Project

  • Build all modules: mvn install from root.
  • Recommended for faster builds: mvn install -T 1C -P quick-build.
  • Build specific module: Run mvn commands within the module directory.

Code Formatting

  • Check: mvn fmt:check
  • Format: mvn fmt:format
  • Tip: Run in specific module to save time.

4. Testing Strategy

  • Unit Tests: mvn test.
  • Integration Tests: Module specific, may require emulators or live services.
  • Core Components Testing: Components should have adequate unit and integration tests to ensure coverage and correctness.

5. Style Guide

  1. Minimize visibility scopes. Default to most restrictive access level.
  2. Use short names over fully qualified names.
  3. Avoid calling @ObsoleteApi or @Deprecated methods and classes.
  4. Avoid unnecessary formatting changes to keep diffs clean.
  5. Use mvn for everything other than the test/integration folder.

6. Dependency Management

  • Do not bump external dependency versions unless for CVE or critical bug fix.
  • Avoid introducing new external dependencies if possible. Prefer Java standard library, then opt for existing dependencies.

7. Contribution Guidelines

  • Commits: Conventional Commits <type>(<scope>): <description>.
  • Pull Requests: Submitted via PR, require review. Pull latest from main and resolve conflicts.
  • Testing: All new logic should be accompanied by tests.

8. Specialized Development Guides

For development on core components, refer to the following guides in sdk-platform-java: