Skip to content

docs: add root-level development.md guide for scoped builds#13151

Open
blakeli0 wants to merge 1 commit intomainfrom
docs/add-development-guide
Open

docs: add root-level development.md guide for scoped builds#13151
blakeli0 wants to merge 1 commit intomainfrom
docs/add-development-guide

Conversation

@blakeli0
Copy link
Copy Markdown
Contributor

@blakeli0 blakeli0 commented May 8, 2026

This PR adds a root-level development.md guide that outlines highly efficient scoped build strategies in the monorepo and explains how to handle the imported dependencyManagement BOM edge case.

fixes: #13009

@blakeli0 blakeli0 requested a review from a team as a code owner May 8, 2026 23:15
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a development.md guide to help developers perform efficient, targeted builds within the google-cloud-java monorepo using Maven flags like -pl and -am. The review feedback focuses on correcting misleading examples of reactor dependencies by removing external repositories, clarifying the necessity of mvn install for local BOM resolution, and ensuring command instructions adhere to the repository's root-directory convention.

Comment thread development.md

### Flag Explanations:
* **`-pl <module-path>`**: 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`).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The projects gax-java and google-auth-library-java are external repositories and are not part of the google-cloud-java monorepo reactor. Maven's -am (also make) flag only builds upstream projects that are defined as modules within the same reactor. Including them in this list might mislead developers into thinking they will be built from source.

Suggested change
* **`-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`).
* -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., google-cloud-core).

Comment thread development.md
* 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**:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Per the repository's general rules, documentation should clarify that mvn install is used to build artifacts into the local ~/.m2 repository. This is particularly important for BOMs, as they must be installed to the local repository to be correctly resolved via import by other modules in the reactor, which -am alone does not always handle for imports.

Suggested change
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**:
To resolve this without doing a full 30-minute monorepo build, you can explicitly list the imported BOMs in the -pl parameter and use mvn install to ensure they are built and installed into your local ~/.m2/repository for proper resolution. This takes only ~1 minute:
References
  1. In documentation about the Java build process, clarify that mvn install is used for building snapshot artifacts to the local ~/.m2 repository.

Comment thread development.md

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:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The term "external dependencies" usually refers to third-party libraries (like those from Maven Central). In the context of this monorepo guide, it is clearer to refer to them as "upstream monorepo dependencies" (such as google-cloud-core or shared BOMs) that must be installed before building a specific service. Additionally, per the repository's convention, commands should assume the user is in the repository root.

Suggested change
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:
References
  1. In documentation about the Java build process, clarify that mvn install is used for building snapshot artifacts to the local ~/.m2 repository.
  2. Commands in documentation should assume the user is in the repository root folder, as this is a stated convention in the document.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document how to develop from within a library directory

1 participant