Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
251 changes: 251 additions & 0 deletions java-bigquery-jdbc/.agents/skills/bigquery-jdbc-prepare-pr/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,251 @@
---
name: bigquery-jdbc-prepare-pr
description: Prepare a pull request for the BigQuery JDBC driver (java-bigquery-jdbc) and get it independently reviewed. Before a PR is created, pushed, or marked ready for review, a fresh reviewer agent on a different model checks the diff and the PR description. The author fixes or argues against each finding, and the loop repeats until both the author and the reviewer are satisfied. Docs, config and other non-Java changes get a single review round. Use this skill whenever you are about to open, update, or finish a PR that touches java-bigquery-jdbc.
---

# Preparing a PR with external review

When you (the **author agent**) finish a change, you aren't done when your own
tests pass. Get an independent review from an agent running a **different
model** first, and repeat until you and the reviewer agree the PR is ready.

This skill never pushes or opens a PR by itself. Do that only if the user asked.

```mermaid
flowchart TD
A["1. Sync with main, finish change, run local checks"] --> B["2. Write PR description, build context bundle"]
B --> C["3. Start a FRESH reviewer on a different model"]
C --> D{"Reviewer verdict"}
D -->|"CHANGES_REQUESTED"| E["4. Answer every finding: FIXED, PUSHBACK or WONTFIX"]
D -->|"APPROVE"| G{"Author concerns open, or an answer that changes behaviour?"}
G -->|"yes"| E
G -->|"no"| H["6. Stop and report to the user. Push or open the PR only if asked"]
E --> F["5. Re-run local checks, update description and ledger"]
F -->|"full loop"| C
F -->|"single-round change, nothing blocking"| H
```

## How much review the change needs

| The change | Review |
| --- | --- |
| Edits any `.java` file under `src/`, beyond comments or formatting | **Full loop**: steps 1 to 6. |
| Anything else: docs, Markdown, skills, build or CI config, dependency bumps, comment-only or formatting-only edits | **Single round**: steps 1 to 4 once, then re-run the checks, update the description, and report as in step 6. Go one more round only if the reviewer raised a `blocking` finding, to confirm the fix. |

If you aren't sure which row applies, use the full loop. In a single-round
change, run only the local checks the change can affect.

## 1. Sync with main, finish the change, run local checks

Before you ask anyone to review, the branch must be current and the change must
build and pass its tests:

- Sync: `git fetch origin main`, then bring `origin/main` into the branch. If
the branch is already pushed, merge instead of rebasing unless the user asks
for a rebase, so nobody has to force-push. (`origin` here means the remote for
`googleapis/google-cloud-java`.)
- Format: `make lint` from `java-bigquery-jdbc/`. It rewrites files in place.
- Unit tests: the full suite, `make unittest`, before the first round and again
on the final code. Between rounds the classes you touched are enough:
`make unittest test=<TestClass>`.
- Integration tests compile at least: `mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile`.
- Follow the repo and module `AGENTS.md` and, for test changes, the
`bigquery-jdbc-testing` skill.

## 2. Write the PR description and build the context bundle

Write the PR description now, not after the review. The reviewer checks it too.
It has:

- **Title** in Conventional Commits form: `fix(bigquery-jdbc): ...`.
- **What** changed and **why** (the bug, the issue link, or the requirement).
- **How it was tested**: the commands you ran, new tests, and anything you
couldn't run (for example integration tests that need credentials).
- **Risks / follow-ups**, if any.

**Untracked files are in no diff.** Before you build the bundle, run
`git status --short`. For every `??` file that belongs to the change, run
`git add -N <file>` (or commit it) so the reviewer sees it.

Build a **context bundle** for the reviewer:

1. The PR description, word for word.
2. The full diff from the merge base to your working tree:
`git diff "$(git merge-base origin/main HEAD)"`. One diff covers committed,
staged and unstaged changes.
3. The list of changed files (the same command with `--name-only`) and the repo
path, so the reviewer can open surrounding code itself.
4. From round 2 on, the **review ledger** (see step 4).

Keep the bundle and ledger in a scratch location **outside the repository** (for
example the agent's scratch or artifact directory, or `/tmp`). Never commit them.

## 3. Start a fresh reviewer on a different model

The reviewer must run on a **different model from yours**, so its blind spots
differ from yours. Prefer a model at least as capable as your own. If every
different model you can reach is weaker than yours, use the strongest of them
and say so in the final report, so the user knows how much weight the approval
carries.

Start a **new** reviewer every round. Don't continue an old reviewer
conversation, because it is already anchored on its earlier opinions. The ledger
gives the new reviewer the history it needs.

Save the filled-in prompt as a file in the scratch location (`$PROMPT_FILE`
below). How to start a reviewer, depending on your harness:

| Harness | How to start a different-model reviewer |
| --- | --- |
| Jetski / Antigravity | `invoke_subagent` with a `Model` other than your own, on a read-only type such as `research`. Give it the path of the prompt file, or the prompt itself if it is short. |
| Claude Code | Gemini CLI from the shell: `gemini -p "Review as instructed on stdin." < "$PROMPT_FILE"`. If it isn't installed, use a Task subagent pinned to a different Claude model. |
| Gemini CLI | Claude Code from the shell: `claude -p "Review as instructed on stdin." < "$PROMPT_FILE"`. If it isn't installed, use a subagent on a different Gemini model. |

- Pass the prompt on stdin as shown, not as a command-line argument. Linux
limits a single argument to 128 KiB, and a large diff plus this template
exceeds that.
- The two shell commands send the diff to another company's service. Don't use
them for a security fix that isn't public yet, or where the user or team has
restricted external services. Use the same-vendor fallback in that row
instead.
- If you can't get a different model at all, stop and tell the user. Don't
quietly use your own model to review your own work. If you can't tell which
model you are running on, say that in the final report.

### Reviewer prompt template

```text
You are an independent senior reviewer for a pull request to the google-cloud-java
monorepo, module java-bigquery-jdbc (the BigQuery JDBC driver). You did not write
this code. Be rigorous and specific, and don't rubber-stamp it.

Repository: <absolute repo path> (you may read any file for context)
Base branch: origin/main
Round: <n>

== PR DESCRIPTION ==
<description>

== CHANGED FILES ==
<file list>

== DIFF ==
<diff>

== REVIEW LEDGER FROM EARLIER ROUNDS (empty in round 1) ==
<ledger>

Review for: correctness and edge cases, concurrency and resource leaks
(connections, statements, result sets, threads), JDBC spec compliance, backward
compatibility and public API surface (see AGENTS.md and the api-lifecycle skill),
security (credentials, logging of secrets), test coverage of every new branch,
test quality (see the bigquery-jdbc-testing skill), and whether the PR
description is accurate and complete. For documentation, skill and config
changes, check every factual claim (class names, commands, paths) against the
repository.

From round 2 on:
- For each finding marked FIXED, check the fix in the code. Don't repeat the
finding unless the fix is wrong or incomplete.
- For each finding marked PUSHBACK, say whether you ACCEPT the author's reason
(the finding is then closed) or MAINTAIN it, with a new argument.
- Findings marked WONTFIX are closed nits. Don't repeat them.
- Concentrate on what the ledger says changed since the previous round. Raise a
new finding on code that has not changed since then only if it is blocking or
major.

Reply in exactly this format:

VERDICT: APPROVE | CHANGES_REQUESTED
FINDINGS:
- id: R<round>-<n>
severity: blocking | major | minor | nit
location: <file>:<line> | PR description
issue: <what is wrong and why it matters>
suggestion: <concrete fix>
PUSHBACK_RESPONSES:
- id: <earlier finding id>
decision: ACCEPT | MAINTAIN
reason: <why>

APPROVE only if no blocking or major findings are open.
```

## 4. Answer every finding

Answer **every** finding in the ledger with exactly one of:

- **FIXED**: say what you changed and where (file and lines). The next reviewer
uses this to find the change.
- **PUSHBACK**: you disagree. You **must** give a concrete reason backed by
evidence: a code reference, the JDBC spec, an existing convention in the repo,
a test result, or scope ("out of scope for this PR; tracked in <issue>").
"I prefer it this way" is not a reason.
- **WONTFIX**: for `nit` findings only, with a short reason. It closes the
finding.

Rules:

- Take the findings seriously. Push back only when you are confident the
reviewer is wrong or the request is out of scope. Don't push back to save
effort.
- If the reviewer maintains a pushback, you may answer it once more. If it is
maintained a second time, fix it, or stop and escalate to the user (see
step 6). Don't argue a third round.
- You may also add your **own** open concerns to the ledger, things you are
still unsure about. The loop doesn't end while any of them are open.
- An `APPROVE` can still carry `minor` or `nit` findings. Answer them like any
others. If an answer changes behaviour (anything beyond renames, comments,
formatting, or the PR description), that code has not been reviewed: go
another round. Otherwise re-run the checks and finish.

### Ledger format

Keep one ledger file for the whole loop and append to it every round:

```markdown
## Round <n>, reviewer model: <model>, verdict: <APPROVE|CHANGES_REQUESTED>

| id | severity | finding | author response | status |
| --- | --- | --- | --- | --- |
| R1-1 | blocking | ResultSet leaked on error path in Foo.java:120 | FIXED: try-with-resources in Foo.java:118-131 | closed |
| R1-2 | major | Missing test for default universe | FIXED: added testXForDefaultUniverse in FooTest.java:210-240 | closed |
| R1-3 | minor | Rename helper to assertY | PUSHBACK: name matches existing assertX convention in BarTest | open, awaiting reviewer |
| R1-4 | nit | Blank line before return | WONTFIX: formatter output | closed |

Author open concerns: <none | list>
```

## 5. Re-run checks and loop

After you address the findings:

1. Re-run the local checks from step 1. Every round, not just the first.
2. Update the PR description if the change or the testing changed.
3. Rebuild the context bundle (new diff, updated ledger).
4. Go back to step 3 with a **new** reviewer.

A single-round change stops after item 2, unless the reviewer raised a
`blocking` finding.

## 6. When to stop

The full loop **ends successfully** only when all of these are true:

- The latest reviewer's verdict is `APPROVE`.
- No `blocking` or `major` finding is open, and every pushback is either
ACCEPTED or resolved by a fix.
- You (the author) have no open concerns.
- Nothing that changes behaviour was edited after the last review.
- The local checks, including the full unit suite, pass on the final code.

**Safety limit:** stop after **5 rounds** without agreement, or when a pushback
has been maintained twice and you are not going to fix it. Report the
unresolved items to the user with both sides' arguments and let them decide.
Don't loop forever, and don't declare agreement that didn't happen.

When you stop, report to the user: the number of rounds, the reviewer model(s)
used and whether any was weaker than yours, what changed because of review, any
accepted pushbacks, anything you changed after the last review, any finding
left unfixed, and the final PR description. Push or open the PR only if the
user asked you to.
142 changes: 142 additions & 0 deletions java-bigquery-jdbc/.agents/skills/bigquery-jdbc-testing/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
name: bigquery-jdbc-testing
description: Conventions for writing and refactoring unit and integration tests in the BigQuery JDBC driver (java-bigquery-jdbc). Use this skill when adding, reviewing, or cleaning up tests under java-bigquery-jdbc/src/test, including tests for connection/credential setup, Storage Read/Write API clients, TPC/universe-domain behavior, and ITBase-derived integration tests.
---

# BigQuery JDBC Driver: Writing Tests

Applies to `java-bigquery-jdbc/src/test/java/com/google/cloud/bigquery/jdbc/**`.

- **Unit tests** live in `com.google.cloud.bigquery.jdbc`. A new test class that
needs the shared fixtures extends `BigQueryJdbcBaseTest`, or
`BigQueryJdbcLoggingBaseTest` when it asserts on log output.
- **Integration tests** live in `com.google.cloud.bigquery.jdbc.it` and are
named `IT*`. A new one extends `ITBase` when it uses the shared connection,
datasets, or helpers.

Many existing test classes extend neither base class. Leave their parent alone:
don't re-parent a class unless that is the task you were given.

Aim for tests that are short and read top to bottom: setup comes from shared
fixtures, the test body holds only what is specific to the case, and repeated
assertions live in one helper.

## 1. Reuse existing fixtures. Don't hand-roll them

Before writing setup code, check `BigQueryJdbcBaseTest`,
`BigQueryJdbcLoggingBaseTest`, `utils/TestUtilities`, and `utils/URIBuilder`.

| Need | Use | Avoid |
| --- | --- | --- |
| A private key / PEM string | `fake_pkcs8_key` | `KeyPairGenerator`, Base64 encoding, building `-----BEGIN PRIVATE KEY-----` by hand |
| A service-account connection URL | `getUriOAuthServiceAccount()` | Building `jdbc:bigquery://...;OAuthType=0;...` by string concatenation |
| Other auth types | `getUriOAuthUserAccount()`, `getUriOAuthToken()`, `getUriOAuthApplicationDefault()`, `getUriOAuthExternal()` | Copy-pasting URL fragments |
| Extra URL properties | `.append("Key", value)` on the `URIBuilder`, then `.toString()` | Manual `";"` handling |

Example:

```java
String url =
getUriOAuthServiceAccount()
.append("ProjectId", "project")
.append("universeDomain", "apis-tpczero.goog")
.toString();
```

If a fixture you need doesn't exist and more than one test would use it, add it
to the base class instead of keeping a private copy in one test file.

## 2. Pull repeated assertions into a helper

When a test asserts the same thing for two or more objects (for example the
Storage **Read** and **Write** clients, or the Arrow and JSON result sets), move
the assertions into one `private static` helper that takes the varying parts
(credentials, endpoint URI, expected scopes, expected universe) as parameters.
Each test then makes one call per object.

This is how `BigQueryConnectionTest` does it. `TPC_UNIVERSE`, `storageUri` and
`assertStorageCredentialsScoped` are private members of that class, not shared
fixtures:

```java
assertStorageCredentialsScoped(
readClient.getSettings().getCredentialsProvider().getCredentials(),
TPC_UNIVERSE,
storageUri(TPC_UNIVERSE, "BigQueryRead"),
BigQueryReadSettings.getDefaultServiceScopes());
assertStorageCredentialsScoped(
writeClient.getSettings().getCredentialsProvider().getCredentials(),
TPC_UNIVERSE,
storageUri(TPC_UNIVERSE, "BigQueryWrite"),
BigQueryWriteSettings.getDefaultServiceScopes());
```

Put repeated literals (universe domains, endpoint URIs, scope lists) in
`private static final` constants at the top of the test class.

## 3. Cover every branch of the code under test

For each conditional in the production change, write at least one test that
takes each side. In particular:

- **Credential type.** If the code special-cases `ServiceAccountCredentials` or
`GoogleCredentials`, also test a credential that is *not* a service account,
such as `getUriOAuthToken()` / `GoogleCredentials.create(AccessToken)`. Check
that it passes through unchanged (`assertSame` where possible).
- **Universe domain.** If the code behaves differently for TPC
(`universeDomain=apis-tpczero.goog`), also test the **default** universe (no
`universeDomain` property, so `googleapis.com`).
- **Already configured input.** For example, credentials that already have
explicit scopes must keep them.

When you are asked to *refactor* tests, keep coverage the same: every assertion
the old tests made must still be made, possibly through a helper. Don't drop
cases or weaken assertions (for example, changing `assertEquals` to
`assertNotNull`).

## 4. Integration tests: shared pieces belong in `ITBase`

- Read `ITBase` before you add a query template or a check. It is the source of
truth for what is shared. It already has, for example,
`GENERATE_ARRAY_QUERY` (used as `String.format(GENERATE_ARRAY_QUERY, n)`),
`assertArrowResultSet(ResultSet)` (proves the High-Throughput, Storage Read
API path was taken), `resultSetRowCount(ResultSet)` and
`validateStatement(...)`.
- If more than one `IT*` class uses the same query template or check, define it
once in `ITBase`. Don't redefine it per class or inline the literal. Use the
least visibility that works: `protected static` is enough unless something
outside the `ITBase` hierarchy needs it.
- Don't give a class-local constant or helper the same name as an `ITBase`
member. A same-named field that means something else hides the shared one and
misleads the reader.
- Use try-with-resources for `Connection`, `Statement`, and `ResultSet`, or close
them explicitly. IT suites share quotas.
- `@Tag("disable_tpc")` excludes a test from TPC runs. Remove it only when the
feature is known to work against TPC, and in that case add an assertion that
proves the intended path was used (for example `assertArrowResultSet`).

## 5. Style and verification

- Follow the repo and module `AGENTS.md`: least visibility (`private static`
helpers), short names over fully qualified names, no
`@Deprecated`/`@ObsoleteApi` calls, no Mockito mocks of final JDK types, and
no unrelated formatting changes.
- Remove imports that the refactor makes unused (for example `KeyPairGenerator`,
`PrivateKey`, `Base64`).
- Run the formatter from `java-bigquery-jdbc/`:
```bash
make lint # mvn com.spotify.fmt:fmt-maven-plugin:format
```
If the formatter fails with `NoSuchMethodError`, your JDK is too new for
google-java-format. Run it under JDK 17, which is what the CI lint job uses:
`JAVA_HOME=<path to a JDK 17> make lint`.
- Run the affected unit tests:
```bash
make unittest test=BigQueryConnectionTest
make unittest test='BigQueryConnectionTest#testReadAndWrite*'
```
- Integration tests need real credentials (`GOOGLE_APPLICATION_CREDENTIALS`).
If they can't run locally, at least compile them:
```bash
mvn -q -Denforcer.skip=true -Dclirr.skip=true test-compile
```
1 change: 1 addition & 0 deletions java-bigquery-jdbc/.claude/skills
Loading
Loading