From 13ff9af64c302a9b3c400555e4297ae0d891214b Mon Sep 17 00:00:00 2001 From: Ed Burns Date: Fri, 5 Jun 2026 12:51:23 -0700 Subject: [PATCH 1/3] Java: adr recording decision to keep everything in one module --- .../adr-003-sub-module-for-generated-code.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 java/docs/adr/adr-003-sub-module-for-generated-code.md diff --git a/java/docs/adr/adr-003-sub-module-for-generated-code.md b/java/docs/adr/adr-003-sub-module-for-generated-code.md new file mode 100644 index 000000000..a43a7cee4 --- /dev/null +++ b/java/docs/adr/adr-003-sub-module-for-generated-code.md @@ -0,0 +1,35 @@ +# Sub-module for generated code + +## Context and Problem Statement + +Regarding the goal of more effectively passing on the stability and deprecation metadata from the `@github/copilot` Zod schema to end consumers of `copilot-sdk-java`, Partner Software Engineer Stephen Toub stated, "The ideal is to do the best each language has to offer." + +## Considered Options + +* Status quo: keep generated code in the same `copilot-sdk-java` module. + +* Option 1: Move all generated code (both `com.github.copilot.generated` and `com.github.copilot.generated.rpc`) to a single internal Maven module (`copilot-sdk-generated`), bundled back into the published `copilot-sdk-java` artifact via `maven-dependency-plugin`. + +* Option 2: Move generated code into two internal Maven modules (`copilot-sdk-events` for session-event types, `copilot-sdk-rpc-generated` for RPC types), bundled back into the published artifact. + +### Analysis + +The generated code is deeply embedded in the public API surface of `copilot-sdk-java`: `CopilotSession.getRpc()` returns `SessionRpc`, `CopilotClient.getRpc()` returns `ServerRpc`, `sendAndWait()` returns `AssistantMessageEvent`, and the event handler API accepts all generated event subclasses. Approximately 730 of 914 generated classes are part of the externally-visible API. Any module split is therefore a build-time concern only — it cannot reduce the consumer-facing footprint. + +The dependency direction is clean (hand-written → generated, never reverse), making a split technically feasible without circular dependencies. + +However, the specific goal of conveying stability/deprecation metadata requires a `@CopilotExperimental` annotation visible at compile time to both the generated and hand-written code. In the status quo, this annotation lives in `src/main/java/` and is freely importable by `src/generated/java/` since they compile together. In a split-module reactor, the generated module compiles *before* the hand-written module, so the annotation must either be emitted by the codegen script as another generated file, or extracted into a third annotations-only module. Both add complexity without advancing the stability-metadata goal. + +Module separation is orthogonal to — and slightly complicates — the stability/deprecation work. The codegen script changes to read and propagate `stability`/`deprecated` from schema nodes are identical regardless of module structure. + +## Decision Outcome + +Keep the status quo: keep the generated code in the same `copilot-sdk-java` module. + +The primary benefit of module separation (compile-time isolation, cleaner PR diffs) does not justify the added reactor complexity, `maven-dependency-plugin` configuration, and annotation-placement constraints — particularly given that the immediate priority is implementing stability/deprecation metadata propagation, which is simpler in a single-module build. + +## Related work items + +- https://devdiv.visualstudio.com/DevDiv/_workitems/edit/3013416 + +- https://github.com/github/copilot-sdk/issues/1573 From 500bd59cb6966aa1481e910ec51750ecc99cdd1e Mon Sep 17 00:00:00 2001 From: Ed Burns Date: Fri, 5 Jun 2026 13:04:21 -0700 Subject: [PATCH 2/3] ci: skip java-kotlin CodeQL for docs/txt/md-only changes --- .github/workflows/codeql.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index fcdac9fdd..e7d5bf4f3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -32,6 +32,9 @@ jobs: filters: | java: - 'java/**' + - '!java/docs/**' + - '!java/*.txt' + - '!java/*.md' js: - 'nodejs/**' - 'scripts/**' From 3be53e23552d85b46eb73c7dd48c496e1bd46465 Mon Sep 17 00:00:00 2001 From: Ed Burns Date: Fri, 5 Jun 2026 13:07:06 -0700 Subject: [PATCH 3/3] ci: skip sdk-consistency-review for java docs/txt/md-only changes --- .../workflows/sdk-consistency-review.lock.yml | 29 ++++++++++--------- .github/workflows/sdk-consistency-review.md | 3 ++ 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/.github/workflows/sdk-consistency-review.lock.yml b/.github/workflows/sdk-consistency-review.lock.yml index 955d511ee..3cffd9d38 100644 --- a/.github/workflows/sdk-consistency-review.lock.yml +++ b/.github/workflows/sdk-consistency-review.lock.yml @@ -1,4 +1,4 @@ -# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"fd14e2b0d7d0348c538098c90367790a391f7cef7b84b1ac91e627a7f88bc063","body_hash":"97333b6724b46fcc7c9d59c1eec7c424d3a2005fab0e52e2520c97a02021426b","compiler_version":"v0.77.5","strict":true,"agent_id":"copilot"} +# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"7705f1f36359046432427c7379dff5ce45f49f1d69e23433af41c1234042e51b","body_hash":"97333b6724b46fcc7c9d59c1eec7c424d3a2005fab0e52e2520c97a02021426b","compiler_version":"v0.77.5","strict":true,"agent_id":"copilot"} # gh-aw-manifest: {"version":1,"secrets":["COPILOT_GITHUB_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/checkout","sha":"de0fac2e4500dabe0009e67214ff5f5447ce83dd","version":"v6.0.2"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e","version":"v6.4.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"3ea13c02d765410340d533515cb31a7eef2baaf0","version":"v0.77.5"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.25.58"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.25.58"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.25.58"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.3.22"},{"image":"ghcr.io/github/github-mcp-server:v1.1.0"},{"image":"node:lts-alpine","digest":"sha256:2bdb65ed1dab192432bc31c95f94155ca5ad7fc1392fb7eb7526ab682fa5bf14","pinned_image":"node:lts-alpine@sha256:2bdb65ed1dab192432bc31c95f94155ca5ad7fc1392fb7eb7526ab682fa5bf14"}]} # ___ _ _ # / _ \ | | (_) @@ -56,6 +56,9 @@ on: - go/** - dotnet/** - java/** + - "!java/docs/**" + - "!java/*.txt" + - "!java/*.md" types: - opened - synchronize @@ -219,20 +222,20 @@ jobs: run: | bash "${RUNNER_TEMP}/gh-aw/actions/create_prompt_first.sh" { - cat << 'GH_AW_PROMPT_9c21fe6e74693154_EOF' + cat << 'GH_AW_PROMPT_cf79d4d226819b37_EOF' - GH_AW_PROMPT_9c21fe6e74693154_EOF + GH_AW_PROMPT_cf79d4d226819b37_EOF cat "${RUNNER_TEMP}/gh-aw/prompts/xpia.md" cat "${RUNNER_TEMP}/gh-aw/prompts/temp_folder_prompt.md" cat "${RUNNER_TEMP}/gh-aw/prompts/markdown.md" cat "${RUNNER_TEMP}/gh-aw/prompts/safe_outputs_prompt.md" - cat << 'GH_AW_PROMPT_9c21fe6e74693154_EOF' + cat << 'GH_AW_PROMPT_cf79d4d226819b37_EOF' Tools: add_comment, create_pull_request_review_comment(max:10), missing_tool, missing_data, noop - GH_AW_PROMPT_9c21fe6e74693154_EOF + GH_AW_PROMPT_cf79d4d226819b37_EOF cat "${RUNNER_TEMP}/gh-aw/prompts/mcp_cli_tools_prompt.md" - cat << 'GH_AW_PROMPT_9c21fe6e74693154_EOF' + cat << 'GH_AW_PROMPT_cf79d4d226819b37_EOF' The following GitHub context information is available for this workflow: {{#if github.actor}} @@ -261,12 +264,12 @@ jobs: {{/if}} - GH_AW_PROMPT_9c21fe6e74693154_EOF + GH_AW_PROMPT_cf79d4d226819b37_EOF cat "${RUNNER_TEMP}/gh-aw/prompts/github_mcp_tools_with_safeoutputs_prompt.md" - cat << 'GH_AW_PROMPT_9c21fe6e74693154_EOF' + cat << 'GH_AW_PROMPT_cf79d4d226819b37_EOF' {{#runtime-import .github/workflows/sdk-consistency-review.md}} - GH_AW_PROMPT_9c21fe6e74693154_EOF + GH_AW_PROMPT_cf79d4d226819b37_EOF } > "$GH_AW_PROMPT" - name: Interpolate variables and render templates uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0 @@ -482,9 +485,9 @@ jobs: mkdir -p "${RUNNER_TEMP}/gh-aw/safeoutputs" mkdir -p /tmp/gh-aw/safeoutputs mkdir -p /tmp/gh-aw/mcp-logs/safeoutputs - cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_cebed10e1a4086f5_EOF' + cat > "${RUNNER_TEMP}/gh-aw/safeoutputs/config.json" << 'GH_AW_SAFE_OUTPUTS_CONFIG_ee26456e9d33cb21_EOF' {"add_comment":{"hide_older_comments":true,"max":1},"create_pull_request_review_comment":{"max":10,"side":"RIGHT"},"create_report_incomplete_issue":{},"missing_data":{},"missing_tool":{},"noop":{"max":1,"report-as-issue":"true"},"report_incomplete":{}} - GH_AW_SAFE_OUTPUTS_CONFIG_cebed10e1a4086f5_EOF + GH_AW_SAFE_OUTPUTS_CONFIG_ee26456e9d33cb21_EOF - name: Generate Safe Outputs Tools env: GH_AW_TOOLS_META_JSON: | @@ -716,7 +719,7 @@ jobs: mkdir -p /home/runner/.copilot GH_AW_NODE=$(which node 2>/dev/null || command -v node 2>/dev/null || echo node) - cat << GH_AW_MCP_CONFIG_c021793c682dcff5_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs" + cat << GH_AW_MCP_CONFIG_f1f5e8d8750acfbe_EOF | "$GH_AW_NODE" "${RUNNER_TEMP}/gh-aw/actions/start_mcp_gateway.cjs" { "mcpServers": { "github": { @@ -757,7 +760,7 @@ jobs: "payloadDir": "${MCP_GATEWAY_PAYLOAD_DIR}" } } - GH_AW_MCP_CONFIG_c021793c682dcff5_EOF + GH_AW_MCP_CONFIG_f1f5e8d8750acfbe_EOF - name: Mount MCP servers as CLIs id: mount-mcp-clis continue-on-error: true diff --git a/.github/workflows/sdk-consistency-review.md b/.github/workflows/sdk-consistency-review.md index b6e2bb0d4..4111015ba 100644 --- a/.github/workflows/sdk-consistency-review.md +++ b/.github/workflows/sdk-consistency-review.md @@ -11,6 +11,9 @@ on: - 'go/**' - 'dotnet/**' - 'java/**' + - '!java/docs/**' + - '!java/*.txt' + - '!java/*.md' workflow_dispatch: inputs: pr_number: