From 2cbddd32f901a3e15a40981b8f0c8c946cc69f63 Mon Sep 17 00:00:00 2001 From: blakeli Date: Fri, 8 May 2026 19:15:38 -0400 Subject: [PATCH 1/5] docs: add root-level development.md guide for scoped builds --- development.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 development.md diff --git a/development.md b/development.md new file mode 100644 index 000000000000..f740d5317ab3 --- /dev/null +++ b/development.md @@ -0,0 +1,51 @@ +# Monorepo Scoped Development Guide + +This document outlines highly efficient development workflows and build strategies when working with specific client libraries or modules in the `google-cloud-java` monorepo. + +--- + +## 1. Building a Specific Service (Fast Reactor Builds) + +Instead of running a full build of the entire monorepo (which contains over 250+ modules and can take up to 30 minutes), you can target a single client library and let Maven automatically resolve and build all of its upstream dependencies using the `-pl` (project list) and `-am` (also make) flags. + +Run the following command from the **root directory** of the repository: + +```bash +mvn compile -pl java-spanner/google-cloud-spanner -am -P quick-build -DskipTests +``` + +### Flag Explanations: +* **`-pl `**: Targets only the specified project module. +* **`-am` (Also Make)**: Tells Maven to analyze the dependency tree and automatically compile any projects in the reactor that the target library depends on (e.g., `gax-java`, `google-auth-library-java`, `google-cloud-core`). +* **`-P quick-build`**: Bypasses unnecessary verification checks (like Checkstyle, Enforcer, Animal Sniffer) to significantly speed up local iteration. +* **`-DskipTests`**: Skips running unit and integration tests during compilation. + +### Edge Case: Imported BOMs in `` + +> [!WARNING] +> **Maven's `-am` (Also Make) reactor analysis does not automatically build imported BOMs.** + +#### The Problem: +If a module (or one of its parent dependencies/dependency BOMs) imports another BOM from within the same monorepo via `import` in a `` block, Maven **does not** recognize it as a concrete build dependency. +* *Example:* `google-cloud-bigtable-deps-bom` imports `google-cloud-monitoring-bom` via ``. +* Running `mvn compile -pl java-bigtable/google-cloud-bigtable -am` (or targeting the deps-bom directly) will **succeed without actually building the local version of `google-cloud-monitoring-bom`**. Any local changes you made to the BOM will be silently ignored because `-am` does not trace imports. + +#### The Solution (Fast Targeted Build): +To resolve this without doing a full 30-minute monorepo build, you can explicitly list the imported BOMs in the `-pl` parameter. This registers them as primary targets so that `-am` builds them and their dependencies, taking **only ~1 minute**: + +```bash +mvn install -pl java-monitoring/google-cloud-monitoring-bom,java-bigtable/google-cloud-bigtable-deps-bom,java-bigtable/google-cloud-bigtable -am -P quick-build -DskipTests +``` + +--- + +## 2. Building All Submodules under a Service Directory + +Many services in this repository (e.g., `java-spanner`, `java-bigtable`) are structured as aggregator parents with multiple submodules (e.g., separate directories for client code, gRPC/Protobuf stubs, executors, and BOMs). + +Once your external dependencies are installed in your local `~/.m2/repository` cache, you can navigate directly to the service folder and run standard Maven commands: + +```bash +cd java-spanner +mvn compile +``` From 6c577d5c7bdc43d2d039f019836ad89dbb456a3e Mon Sep 17 00:00:00 2001 From: Blake Li Date: Mon, 11 May 2026 15:44:05 -0400 Subject: [PATCH 2/5] Update development.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/development.md b/development.md index f740d5317ab3..4d3312bc1767 100644 --- a/development.md +++ b/development.md @@ -43,7 +43,7 @@ mvn install -pl java-monitoring/google-cloud-monitoring-bom,java-bigtable/google Many services in this repository (e.g., `java-spanner`, `java-bigtable`) are structured as aggregator parents with multiple submodules (e.g., separate directories for client code, gRPC/Protobuf stubs, executors, and BOMs). -Once your external dependencies are installed in your local `~/.m2/repository` cache, you can navigate directly to the service folder and run standard Maven commands: +Once your upstream monorepo dependencies are installed in your local ~/.m2/repository cache, you can run standard Maven commands for a specific service from the repository root using the -pl flag: ```bash cd java-spanner From 39f48845a1e0ed06e56bec045928fcb2fcc6173d Mon Sep 17 00:00:00 2001 From: blakeli Date: Mon, 11 May 2026 15:45:18 -0400 Subject: [PATCH 3/5] docs(development): align Section 2 code block with root-level -pl description --- development.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/development.md b/development.md index 4d3312bc1767..41de3d4af770 100644 --- a/development.md +++ b/development.md @@ -46,6 +46,5 @@ Many services in this repository (e.g., `java-spanner`, `java-bigtable`) are str Once your upstream monorepo dependencies are installed in your local ~/.m2/repository cache, you can run standard Maven commands for a specific service from the repository root using the -pl flag: ```bash -cd java-spanner -mvn compile +mvn compile -pl java-spanner ``` From 46ad0be97ac649071687b3d426d073157712b547 Mon Sep 17 00:00:00 2001 From: blakeli Date: Mon, 11 May 2026 15:53:37 -0400 Subject: [PATCH 4/5] docs(development.md): incorporate user edits for install commands and IDE integration --- development.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/development.md b/development.md index 41de3d4af770..9fd27ec5903c 100644 --- a/development.md +++ b/development.md @@ -1,6 +1,6 @@ # Monorepo Scoped Development Guide -This document outlines highly efficient development workflows and build strategies when working with specific client libraries or modules in the `google-cloud-java` monorepo. +This document outlines development workflows and build strategies when working with specific client libraries or modules in the `google-cloud-java` monorepo. --- @@ -11,7 +11,7 @@ Instead of running a full build of the entire monorepo (which contains over 250+ Run the following command from the **root directory** of the repository: ```bash -mvn compile -pl java-spanner/google-cloud-spanner -am -P quick-build -DskipTests +mvn install -pl java-spanner/google-cloud-spanner -am -P quick-build -DskipTests ``` ### Flag Explanations: @@ -28,10 +28,10 @@ mvn compile -pl java-spanner/google-cloud-spanner -am -P quick-build -DskipTests #### The Problem: If a module (or one of its parent dependencies/dependency BOMs) imports another BOM from within the same monorepo via `import` in a `` block, Maven **does not** recognize it as a concrete build dependency. * *Example:* `google-cloud-bigtable-deps-bom` imports `google-cloud-monitoring-bom` via ``. -* Running `mvn compile -pl java-bigtable/google-cloud-bigtable -am` (or targeting the deps-bom directly) will **succeed without actually building the local version of `google-cloud-monitoring-bom`**. Any local changes you made to the BOM will be silently ignored because `-am` does not trace imports. +* Running `mvn install -pl java-bigtable/google-cloud-bigtable -am` (or targeting the deps-bom directly) will **succeed without actually building the local version of `google-cloud-monitoring-bom`**. -#### The Solution (Fast Targeted Build): -To resolve this without doing a full 30-minute monorepo build, you can explicitly list the imported BOMs in the `-pl` parameter. This registers them as primary targets so that `-am` builds them and their dependencies, taking **only ~1 minute**: +#### The Solution (Targeted Build): +To resolve this without doing a full 30-minute monorepo build, you can explicitly list the imported BOMs in the `-pl` parameter: ```bash mvn install -pl java-monitoring/google-cloud-monitoring-bom,java-bigtable/google-cloud-bigtable-deps-bom,java-bigtable/google-cloud-bigtable -am -P quick-build -DskipTests @@ -46,5 +46,8 @@ Many services in this repository (e.g., `java-spanner`, `java-bigtable`) are str Once your upstream monorepo dependencies are installed in your local ~/.m2/repository cache, you can run standard Maven commands for a specific service from the repository root using the -pl flag: ```bash -mvn compile -pl java-spanner +cd java-spanner +mvn compile ``` + +Your IDE such as Intellij should also be able to import all the upstream dependencies at this moment. You can perform the same operations as you would in a normal project such as running unit tests, debugging and so on. From 85e775192c95982654c84acd3cb11d5a92ac58bc Mon Sep 17 00:00:00 2001 From: blakeli Date: Mon, 11 May 2026 17:11:55 -0400 Subject: [PATCH 5/5] docs: rename development.md to uppercase DEVELOPMENT.md --- development.md => DEVELOPMENT.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename development.md => DEVELOPMENT.md (100%) diff --git a/development.md b/DEVELOPMENT.md similarity index 100% rename from development.md rename to DEVELOPMENT.md