docs: add root-level development.md guide for scoped builds#13151
docs: add root-level development.md guide for scoped builds#13151
Conversation
There was a problem hiding this comment.
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.
|
|
||
| ### 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`). |
There was a problem hiding this comment.
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.
| * **`-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). |
| * 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**: |
There was a problem hiding this comment.
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.
| 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
- In documentation about the Java build process, clarify that mvn install is used for building snapshot artifacts to the local ~/.m2 repository.
|
|
||
| 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: |
There was a problem hiding this comment.
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.
| 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
- In documentation about the Java build process, clarify that mvn install is used for building snapshot artifacts to the local ~/.m2 repository.
- Commands in documentation should assume the user is in the repository root folder, as this is a stated convention in the document.
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