Skip to content

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

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

Draft
quartzmo wants to merge 1 commit into
base: main
Choose a base branch
from
+25 −0
Draft

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

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
25 changes: 25 additions & 0 deletions .gemini/GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Google API Go Client (`google-api-go-client`) Context

## Repository Overview
This repository contains the auto-generated Go client libraries for Google APIs, based on the **Discovery API**.

* **Nature of Code:** Almost every top-level directory (e.g., `calendar/`, `drive/`, `sheets/`) corresponds to a Google API and is **auto-generated**.
* **Editing:** Avoid manual edits to specific API clients unless absolutely necessary for debugging. Changes should ideally happen in the generator or the source discovery doc.

## Key Directories
While most directories are clients, the following are the core libraries that support them:

* `googleapi/`: Contains common types, error handling, and JSON helpers used across all clients. **High importance** for cross-cutting concerns.
* `transport/`: Handles HTTP transport, authentication, and connection pooling. **Critical** for networking behavior.
* `option/`: Configuration options for clients (e.g., API keys, credentials, endpoints).
* `idtoken/`: Functionality for validating and generating Google ID tokens.
* `internal/`: Shared internal logic.

## Architecture & Wiring
* **Transport Creation (`transport/http/dial.go`):** This is the **critical chokepoint** for all HTTP clients. `NewClient` calls `dial`, which constructs the `http.Client`.
* **Instrumentation Point:** This is the exact location to wrap the `http.Transport` (e.g., with OpenTelemetry) or inject middleware.
* **Configuration:** Users configure clients using `option.ClientOption` (found in `option/`).
* **`option.WithTracerProvider`:** This option flows into `dial.go` and determines the tracing provider.
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.

Are all these details helpful outside the scope of work on tracing? My only concern is that this is sort of a "partial" architecture description that might limit the focus.

If the real meat of the clients is all in dial and ClientOption then this makes sense.


## Context
* **Difference from `google-cloud-go`:** These clients are based on the JSON Discovery format. They are typically pure REST/HTTP clients. The clients in `google-cloud-go` are often gRPC-based (GAPIC) and considered "idiomatic" for Google Cloud Platform services.