|
| 1 | +--- |
| 2 | +name: java-development |
| 3 | +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. |
| 4 | +--- |
| 5 | + |
| 6 | +# Java Development Guide |
| 7 | + |
| 8 | +This skill provides general guidelines for Java development inside the monorepo. It covers building, formatting, testing, and style conventions to ensure consistency across modules. |
| 9 | + |
| 10 | +## Workflow |
| 11 | + |
| 12 | +### 1. Building the Project |
| 13 | + |
| 14 | +The repository uses Maven as its primary build system. |
| 15 | + |
| 16 | +* **Build All Modules**: To build all modules from the root of the repository, run: |
| 17 | + ```bash |
| 18 | + mvn install -T 1C -P quick-build |
| 19 | + ``` |
| 20 | + > [!TIP] |
| 21 | + > Use `-T 1C` to build modules in parallel (one thread per CPU core) and `-P quick-build` to skip unnecessary plugins for faster builds. |
| 22 | +* **Build a Specific Module**: You can also run Maven commands within a specific module directory (e.g., `java-bigquery`) to build only that module. |
| 23 | + |
| 24 | +### 2. Code Formatting |
| 25 | + |
| 26 | +Code formatting is enforced using the `fmt-maven-plugin`. |
| 27 | + |
| 28 | +* **Check Formatting**: To check for formatting issues without modifying files, run: |
| 29 | + ```bash |
| 30 | + mvn fmt:check -T 1C |
| 31 | + ``` |
| 32 | +* **Apply Formatting**: To automatically format the code according to the project style, run: |
| 33 | + ```bash |
| 34 | + mvn fmt:format -T 1C |
| 35 | + ``` |
| 36 | + > [!TIP] |
| 37 | + > To save time, run `mvn fmt:format` within the specific module directory you are working on, rather than at the root. |
| 38 | + > [!NOTE] |
| 39 | + > Always run `mvn fmt:format` before committing changes to avoid build failures due to formatting. |
| 40 | + |
| 41 | +### 3. Testing Strategy |
| 42 | + |
| 43 | +* **Unit Tests**: Traditional unit tests should be added for individual classes and methods. Run them using: |
| 44 | + ```bash |
| 45 | + mvn test -T 1C |
| 46 | + ``` |
| 47 | +* **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. |
| 48 | +
|
| 49 | +### 4. Style Guide |
| 50 | +
|
| 51 | +Follow these general rules to maintain code quality and consistency: |
| 52 | +
|
| 53 | +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. |
| 54 | +2. Avoid Fully Qualified Names: Use imports to keep class names short and readable, rather than using fully qualified names in the code. |
| 55 | +3. **Avoid Obsolete APIs**: Do not call methods marked with `@ObsoleteApi` or `@Deprecated` unless there are no viable alternatives. |
| 56 | +4. **Clean Diffs**: Avoid unnecessary formatting changes or whitespace modifications to keep diffs clean and easy to review. |
| 57 | +
|
| 58 | +### 5. Dependency Management |
| 59 | +
|
| 60 | +* **Version Bumps**: Try not to bump any external dependency versions unless there is a known security vulnerability (CVE) or a critical bug fix. |
| 61 | +* **New Dependencies**: Avoid introducing new external dependencies. If a new dependency is required, provide a strong justification in the pull request. |
| 62 | +* **Standard Library First**: Prefer to use features from the Java standard library, followed by existing dependencies in the project (preferably Google-managed dependencies). |
| 63 | +
|
| 64 | +### 6. Contribution Guidelines |
| 65 | +
|
| 66 | +* **Commit Messages**: Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. Include the module as the scope (e.g., `feat(spanner): ...`, `fix(bigquery): ...`). |
| 67 | +* **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. |
0 commit comments