Skip to content

chore(.gemini): add GEMINI.md context file #13408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(.gemini): add GEMINI.md context file #13408

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions .gemini/GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Google Cloud Go (`google-cloud-go`) Context

## Repository Overview
This repository contains the Cloud Client Libraries for Go.

* **Primary Distinction:** This repo contains both **hand-written** (or hybrid) clients and **auto-generated** (GAPIC) clients.
* **Generated Code:** The majority of top-level directories (e.g., `aiplatform`, `secretmanager`, `kms`) are auto-generated GAPIC clients.
Copy link

@westarle westarle Nov 26, 2025

Choose a reason for hiding this comment

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

Is it possible to include some clues about where the code is generated from (e.g. "generated by ...")? Ideally an agent would figure out that to make a change in secretmanager they need to go change some other module or repo.

* **Do not edit these manually** to fix logic bugs, as changes will be overwritten.
Copy link

@westarle westarle Nov 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Since we don't enumerate folders, help by giving some kind of cue.

Suggested change
* **Do not edit these manually** to fix logic bugs, as changes will be overwritten.
* **Do not edit these manually** to fix logic bugs, as changes will be overwritten.
* **Identification:** Always check the first 5 lines for a "Code generated by..." header

* Only edit them if you are debugging the generation process itself.
Copy link

@westarle westarle Nov 26, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Optional, to be more clear about their use.

Suggested change
* Only edit them if you are debugging the generation process itself.
* They are useful if you need to review or test the output of the generation process, or if you need to integrate with specific services.
* Only edit them if you are prototyping changes to the generation process.


## Hand-Written & Hybrid Clients
The following modules contain significant hand-written code and are actively maintained. These are high-priority targets for reading and editing, as opposed to pure generated code:

* `auth/` (and `auth/oauth2adapt`)
* `bigquery/`
* `bigtable/`
* `compute/metadata/`
* `datastore/`
* `errorreporting/`
* `firestore/`
* `logging/`
* `longrunning/`
* `profiler/`
* `pubsub/` (and `pubsublite/`)
* `spanner/`
* `storage/`
* `vertexai/`

## Internal Package (`internal/`)
The `internal/` directory contains both critical shared utilities and code generation tools.

* **Useful Utilities (Good to Browse):**
* `retry.go`: Shared retry logic.
* `trace/`, `tracecontext/`: Internal tracing support.
* `version/`: Versioning logic.
* `optional/`: Optional primitive types.
* `fields/`: Field handling.
* `testutil/`: Common testing helpers.
* **Ignorable (Tools & Generated):**
* `generated/`: Contains generated snippets and other artifacts. **Do not edit.**
* `gapicgen/`: Tools for running the GAPIC generator.
* `godocfx/`: Documentation generator tools.
* `aliasgen/`, `aliasfix/`: Alias management tools.

## Architecture & Wiring
* **Dependency Flow:** Generated clients in this repo depend heavily on:
* **`google.golang.org/api/option`** (from `google-api-go-client`) for configuration.
* **`github.com/googleapis/gax-go/v2`** for retries and operation management.
* **Transport:** Most clients here use gRPC by default but can fallback to HTTP/JSON. The transport setup logic is generated into the client constructors.

## Development
* **Tests:** Run tests using `go test ./...`.
* **Linting:** Adhere strictly to standard Go style (`gofmt`).