Skip to content

Commit 0a46c0b

Browse files
chingor13gemini-code-assist[bot]
chingor13
and
gemini-code-assist[bot]
authored
chore(sdk-platform-java): restore GEMINI.md and DEVELOPMENT.md (#12656)
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 parent 839d625 commit 0a46c0b

File tree

2 files changed

+215
-0
lines changed

2 files changed

+215
-0
lines changed

‎sdk-platform-java/DEVELOPMENT.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Development Setup
2+
3+
You need Java 11 or higher to run the build. The build produces Java 8-compatible
4+
bytecode.
5+
6+
Install [`bazelisk`](https://github.com/bazelbuild/bazelisk) in your `PATH`
7+
for gapic-generator-java's Bazel build.
8+
9+
## Set Up
10+
11+
1. Clone this repo.
12+
13+
2. (OPTIONAL) Copy the Git pre-commit hooks. This will automatically check the build, run
14+
tests, and perform linting before each commit. (Symlinks don't seem to work,
15+
but if you find a way, please add it here!)
16+
17+
```sh
18+
cp .githooks/pre-commit .git/hooks/pre-commit
19+
```
20+
21+
## Run Tests for All Modules
22+
23+
- Run all unit tests in all modules.
24+
25+
```sh
26+
mvn install
27+
```
28+
29+
## Code Formatting
30+
31+
- Run linter checks without actually doing the formatting.
32+
33+
```sh
34+
mvn fmt:check
35+
```
36+
37+
- Format files.
38+
39+
```sh
40+
mvn fmt:format
41+
```
42+
43+
## Testing guide
44+
There are 4 layers of testing in this repo:
45+
1. Traditional unit tests. These tests usually focus on testing one very specific test case at a time. For example, [MethodTest](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/model/MethodTest.java)
46+
2. Golden unit tests. These tests start with a test proto, we create different test cases in the proto, load the proto in unit tests and save the generated file as golden files. For example, [routing header proto](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/proto/explicit_dynamic_routing_header_testing.proto) -> Load in the [unit test](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/GrpcServiceStubClassComposerTest.java#L56-L64) -> Saved as [golden](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/goldens/GrpcRoutingHeadersStub.golden)
47+
3. Showcase integration tests. They test the generated library's behavior against a mock server, see [README.md](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/java-showcase/README.md) of showcase module for details.
48+
4. Golden integration tests. These tests generate a full client library with real protos from googleapis, for example, golden integration tests for [compute](https://github.com/googleapis/sdk-platform-java/tree/main/test/integration/goldens/compute). However, we _should_ stop adding new ones, and rely on golden unit tests and showcase tests.
49+
50+
Based on where the code changes are, we should add different tests, in general
51+
52+
- If the changes are in `gax` or `api-common` only, you _must_ add traditional unit tests, you _may_ add showcase integration tests if you are modifying a public setting.
53+
- If the changes are in `gapic-generator-java` only, showcase integration tests are most likely not needed
54+
- If they are in the `composer` module, you _must_ add golden unit tests, you _may_ add traditional unit tests for better coverage and easier testing.
55+
- If they are in the `parser` module, you _should_ add traditional unit tests with a test proto if possible, you _may_ add golden unit tests to easily see the changes. For example, [routing_rule_parser_testing](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/proto/routing_rule_parser_testing.proto) that is only used for testing [RoutingRuleParser](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/protoparser/RoutingRuleParser.java).
56+
- If they are in `other modules(ast, model, writer etc.)`, you _must_ add traditional unit tests, you _may_ add golden unit tests to easily see the changes.
57+
- If the changes are in both `gax` and `gapic-generator-java`, you _must_ add all test layers, including traditional unit tests, golden unit tests and showcase integration tests.
58+
59+
### How to run tests?
60+
61+
See the [Unit Tests](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/DEVELOPMENT.md#unit-tests) section in gapic-generator-java/DEVELOPMENT.md for how to run traditional and golden unit tests.
62+
63+
See [Running the Integration Tests](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/java-showcase/README.md#running-the-integration-tests) and [Update the Golden Showcase Files](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/java-showcase/README.md#update-the-golden-showcase-files) sections in java-showcase/README.md for how to run and update showcase integration tests.
64+
65+
See the [Integration Tests](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/DEVELOPMENT.md#integration-tests) section in gapic-generator-java/DEVELOPMENT.md for how to run golden integration tests.
66+

‎sdk-platform-java/GEMINI.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Gemini CLI Context for sdk-platform-java
2+
3+
## 1. Overview
4+
5+
This directory, sdk-platform-java, contains the foundational components for building Java client libraries for Google Cloud Platform services. It includes the GAPIC (Generated API Client) generator for Java, the GAX (Google API Extensions) runtime library, and other shared modules.
6+
7+
## 2. Project Structure
8+
9+
The repository is structured into several key modules:
10+
11+
* **`gapic-generator-java`**: The core component for creating new client libraries. It is a Protobuf compiler plugin that generates Java client libraries from API definition files. The `DEVELOPMENT.md` file in this module provides detailed information on how to work with the generator.
12+
13+
* **`gax-java`**: The Google API Extensions for Java (GAX) library. It provides runtime support for the generated client libraries, including features like pagination, request batching, and polling of long-running operations. It has the following submodules:
14+
* `gax`: Transport-independent part of GAX for Java.
15+
* `gax-grpc`: gRPC-specific logic for GAX.
16+
* `gax-httpjson`: REST-specific logic for GAX.
17+
18+
* **`api-common-java`**: Contains foundational types and utilities related to Google APIs. It includes the following packages:
19+
* `core`: Core library containing API stability annotations and wrappers around Guava types.
20+
* `pathtemplate`: Path Template library for manipulating strings that are formatted as Google API resource names.
21+
* `resourcenames`: Resource Name library used by generated resource name types.
22+
23+
* **`java-common-protos`**: Provides Protobuf-generated classes for common Google services that are used across multiple APIs. The code is in this module is auto-generated and should not be modified.
24+
25+
* **`java-iam`**: Contains Protobuf-generated classes for Google's Identity and Access Management (IAM) service, used for managing policies. The code is in this module is auto-generated and should not be modified.
26+
27+
* **`java-showcase`**: A demonstration client library for the "Showcase" API, which is a fake API used for integration testing of the GAPIC generator and GAX library.
28+
29+
* **`java-shared-dependencies`**: Manages shared Maven dependencies for all Google Cloud Java client libraries. This ensures consistency and helps avoid dependency conflicts.
30+
31+
## 3. Getting Started
32+
33+
### 3.1. Prerequisites
34+
35+
To build and work with this project, you will need to install:
36+
37+
* Java 11+
38+
* Maven
39+
40+
### 3.2. Building the Project
41+
42+
The project uses Maven for its primary build system. To build all modules, run the following command from the root of the repository:
43+
44+
```sh
45+
mvn install
46+
```
47+
48+
### 3.3. Code Formatting
49+
50+
Code formatting is enforced using the `fmt-maven-plugin`. To check for formatting issues, run:
51+
52+
```sh
53+
mvn fmt:check
54+
```
55+
56+
To format the code, run:
57+
58+
```sh
59+
mvn fmt:format
60+
```
61+
62+
## 4. Testing
63+
64+
### 4.1. Testing Strategy
65+
66+
The repository employs a multi-layered testing strategy to ensure the quality and correctness of the generated code:
67+
68+
* **Unit Tests:** Traditional unit tests for individual classes and methods. See [unit testing best practices](https://engdoc.corp.google.com/eng/doc/devguide/testing/unit/best-practices.md?cl=head&polyglot=java).
69+
* **Golden Unit Tests:** These tests generate code from test protos and compare the output to "golden" files, which are pre-approved versions of the generated code. These test cases exist inside the `gapic-generator-java` module. See [GrpcServiceStubClassComposerTest](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/java/com/google/api/generator/gapic/composer/grpc/GrpcServiceStubClassComposerTest.java) for an example of golden unit tests. The steps for golden unit tests include creating a test proto, loading the test proto, generating from the test proto, and comparing the result with a golden file.
70+
* **Showcase Integration Tests:** These tests run the generated Showcase client against a local Showcase server to verify end-to-end functionality. This is the preferred way of testing integration tests.
71+
* **Golden Integration Tests:** These tests generate full client libraries for real Google Cloud APIs and compare them to golden versions. This is an older test strategy and showcase testing is preferred.
72+
73+
Based on where the code changes are, we should add different tests, in general
74+
75+
* If the changes are in `gax` or `api-common` only, you _must_ add traditional unit tests, you _may_ add showcase integration tests if you are modifying a public setting.
76+
* If the changes are in `gapic-generator-java` only, showcase integration tests are most likely not needed
77+
* If they are in the `composer` module, you _must_ add golden unit tests, you _may_ add traditional unit tests for better coverage and easier testing.
78+
* If they are in the `parser` module, you _should_ add traditional unit tests with a test proto if possible, you _may_ add golden unit tests to easily see the changes. For example, [routing_rule_parser_testing](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/test/proto/routing_rule_parser_testing.proto) that is only used for testing [RoutingRuleParser](https://github.com/googleapis/google-cloud-java/blob/main/sdk-platform-java/gapic-generator-java/src/main/java/com/google/api/generator/gapic/protoparser/RoutingRuleParser.java).
79+
* If they are in `other modules(ast, model, writer etc.)`, you _must_ add traditional unit tests, you _may_ add golden unit tests to easily see the changes.
80+
- If the changes are in both `gax` and `gapic-generator-java`, you _must_ add all test layers, including traditional unit tests, golden unit tests and showcase integration tests.
81+
82+
### 4.2. Running Unit Tests
83+
84+
Unit tests can be tested via this command:
85+
86+
```sh
87+
mvn test
88+
```
89+
90+
### 4.3. Running Golden Integration Tests
91+
92+
Golden integration tests are run using Bazel. To run all golden integration tests, use the following command from the root of the repository:
93+
94+
```sh
95+
bazelisk test //...
96+
```
97+
98+
Specific integration tests can be run by specifying the target, for example:
99+
100+
```sh
101+
bazelisk test //test/integration:redis
102+
```
103+
104+
### 4.4. Updating Golden Files
105+
106+
If you make changes that affect the generated code, you will need to update the golden files. This can be done using the following command:
107+
108+
```sh
109+
bazelisk run //test/integration:update_asset && bazelisk run //test/integration:update_credentials && bazelisk run //test/integration:update_iam && bazelisk run //test/integration:update_kms && bazelisk run //test/integration:update_pubsub && bazelisk run //test/integration:update_logging && bazelisk run //test/integration:update_redis && bazelisk run //test/integration:update_storage && bazelisk run //test/integration:update_library && bazelisk run //test/integration:update_compute && bazelisk run //test/integration:update_bigtable && bazelisk run //test/integration:update_apigeeconnect
110+
```
111+
112+
### 4.5. Running Showcase Integration Tests
113+
114+
Showcase integration tests are run against a local server that implements the Showcase API. The `java-showcase/README.md` file provides detailed instructions on how to run these tests. The general steps are:
115+
116+
1. **Install the Showcase server:**
117+
118+
```sh
119+
go install github.com/googleapis/gapic-showcase/cmd/gapic-showcase@latest
120+
```
121+
122+
2. **Run the Showcase server:**
123+
124+
```sh
125+
gapic-showcase run
126+
```
127+
128+
3. **Run the integration tests:**
129+
130+
```sh
131+
cd java-showcase
132+
mvn verify -P enable-integration-tests
133+
```
134+
135+
## 5. Dependency Management
136+
137+
- Try not to bump any external dependency version unless there is a known CVE (security or vulnerability issue) or a critical bug fix.
138+
- Try to avoid introducing new external dependencies. If a new dependency is required, please state the reason.
139+
- Prefer to use features from the Java standard library, then try to use features from any existing dependencies (preferably from Google managed dependencies).
140+
141+
## 6. Contribution Guidelines
142+
143+
- **Commits:** Commit messages should follow the [Conventional Commits](https://www.conventionalcommits.org/)
144+
specification. The format is `<type>: <description>`. The type should be one of the following: fix, feat,
145+
build, chore, docs, test, or refactor.
146+
- **Issues:** All significant changes should start with a GitHub issue.
147+
- **Pull Requests:** All code changes must be submitted via a pull request and require review. Before creating a PR, always pull latest from main, merge main to local branch and resolve any conflicts.
148+
- **Testing:** All new logic should be accompanied by tests.
149+
- For more details, see `CONTRIBUTING.md`.

0 commit comments

Comments
 (0)