From 6a88bea299cc0ab7dd6f761b08bf12c60219a6d4 Mon Sep 17 00:00:00 2001 From: Ed Burns Date: Fri, 22 May 2026 15:57:24 -0700 Subject: [PATCH] Add Java-specific content to monorepo copilot-instructions.md Closes #1390 Enrich `.github/copilot-instructions.md` with Java details that were present in the standalone copilot-sdk-java repo but missing from the monorepo variant: - **Developer workflows**: add single-test and format-check commands - **Testing & E2E tips**: add snapshot naming convention (snake_case) - **Conventions & patterns**: add code style bullet (Spotless, fluent setters, Javadoc) and porting guidance (CompletableFuture, Jackson) - **Integration & environment**: add pre-commit hook instructions - **Boundaries section** (new): document generated files that must not be hand-edited (`java/src/generated/java/`, `nodejs/src/generated/`, `test/snapshots/`) --- .github/copilot-instructions.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b058535ba..57a0bbcd7 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -28,6 +28,8 @@ - .NET: `cd dotnet && dotnet test test/GitHub.Copilot.SDK.Test.csproj` - **.NET testing note:** Never add `InternalsVisibleTo` to any project file when writing tests. Tests must only access public APIs. - Java: `cd java && mvn clean verify` (full build + tests), `mvn spotless:apply` (format code before commit) + - Java single test: `cd java && mvn test -Dtest=CopilotClientTest` | single method: `mvn test -Dtest=ToolsTest#testToolInvocation` + - Java format check only: `mvn spotless:check` | Build without tests: `mvn clean package -DskipTests` - **Java testing note:** Always use `mvn verify` without `-q` and without piping through `grep`. Never add `InternalsVisibleTo` equivalent — tests must only access public APIs. ## Testing & E2E tips ⚙️ @@ -36,6 +38,7 @@ - Tests rely on YAML snapshot exchanges under `test/snapshots/` — to add test scenarios, add or edit the appropriate YAML files and update tests. - The harness prints `Listening: http://...` — tests parse this URL to configure CLI or proxy. - Java E2E tests use `E2ETestContext` which manages a `CapiProxy` (Node.js replaying proxy). The harness is cloned during Maven's `generate-test-resources` phase to `java/target/copilot-sdk/`. +- Java test method names are converted to lowercase snake_case for snapshot filenames (avoids case collisions on macOS/Windows). ## Project-specific conventions & patterns ✅ @@ -43,6 +46,8 @@ - Infinite sessions are enabled by default and persist workspace state to `~/.copilot/session-state/{sessionId}`; compaction events are emitted (`session.compaction_start`, `session.compaction_complete`). See language READMEs for usage. - Streaming: when `streaming`/`Streaming=true` you receive delta events (`assistant.message_delta`, `assistant.reasoning_delta`) and final events (`assistant.message`, `assistant.reasoning`) — tests expect this behavior. - Type generation is centralized in `nodejs/scripts/generate-session-types.ts` and requires the `@github/copilot` schema to be present (often via `npm link` or installed package). +- Java code style: 4-space indent (Spotless + Eclipse formatter), fluent setter pattern for config classes, Javadoc required on public APIs (enforced by Checkstyle, except `json`/`events` packages). +- Java handlers return `CompletableFuture` (the Java equivalent of C# `async/await`). When porting from .NET: convert properties → getters/fluent setters, use Jackson (`ObjectMapper`, `@JsonProperty`) for serialization. ## Integration & environment notes ⚠️ @@ -50,6 +55,7 @@ - Some scripts (typegen, formatting) call external tools: `gofmt`, `dotnet format`, `tsx` (available via npm), `quicktype`/`quicktype-core` (used by the Node typegen script), and `prettier` (provided as an npm devDependency). Most of these are available through the repo's package scripts or devDependencies—run `just install` (and `cd nodejs && npm ci`) to install them. Ensure the required tools are available in CI / developer machines. - Tests may assume `node >= 18`, `python >= 3.9`, platform differences handled (Windows uses `shell=True` for npx in harness). - Java requires JDK 17+ and Maven 3.9+. Java E2E tests also require Node.js (for the replay proxy). +- Java pre-commit hook runs `mvn spotless:check`. Enable with `git config core.hooksPath .githooks` (auto-enabled in Copilot coding agent environment via `copilot-setup-steps.yml`). ## Where to add new code or tests 🧭 @@ -57,3 +63,9 @@ - Unit tests: `nodejs/test`, `python/*`, `go/*`, `dotnet/test`, `rust/tests`, `java/src/test/java` - E2E tests: `*/e2e/` folders that use the shared replay proxy and `test/snapshots/`, `java/src/test/java/**/e2e/` - Generated types: update schema in `@github/copilot` then run `cd nodejs && npm run generate:session-types` and commit generated files in `src/generated` or language generated location. Java generated types: `java/src/generated/java` + +## Boundaries — files you must NOT hand-edit ⛔ + +- `java/src/generated/java/` — auto-generated by `scripts/codegen/java.ts`; regenerate with `cd java && mvn generate-sources -Pcodegen`. +- `nodejs/src/generated/` — auto-generated by `npm run generate:session-types`. +- `test/snapshots/` — authoritative test fixtures; add/edit YAML here to change E2E behavior, but don't delete without understanding downstream impact.