Replace ambiguous upstream terminology with reference implementation wording by edburns · Pull Request #77 · github/copilot-sdk-java

edburns · 2026-04-16T22:43:26Z

This change is not cosmetic pedantry. It removes a source of repeated ambiguity that affects contributors, automation, and review quality.

In Git, upstream has a specific technical meaning: the configured tracking branch for a local branch. In this repository, many uses of "upstream" were actually referring to the external reference implementation repository and its commit lineage. Those are not the same concept.

Why this matters:

Reduces onboarding friction: new contributors no longer need to guess whether upstream means a Git remote/tracking branch or the reference implementation project.
Prevents operational mistakes: scripts, workflow docs, and release notes become easier to follow without overloaded terminology.
Improves review precision: comments and PR discussions can distinguish Git mechanics from cross-repo sync intent.
Aligns naming with actual behavior: these workflows are syncing against a reference implementation, not configuring branch upstream tracking.

What this PR does:

Replaces upstream wording with reference implementation (or concise reference-impl where appropriate) across docs, prompts, workflows, and related automation text.
Removes legacy upstream-named sync assets that were superseded by reference-impl equivalents.
Preserves behavior while improving clarity of intent.

This change is deliberately scoped to terminology and clarity. The practical outcome is fewer misunderstandings, safer maintenance, and more accurate communication across the project.

…ing a reference implementation, not an upstream. In `git` an `upstream` is well defined. To avoid LLM confusion, let us use the proper term. new file: .claude/skills/agentic-merge-reference-impl/SKILL.md modified: .github/copilot-instructions.md new file: .github/prompts/agentic-merge-reference-impl.prompt.md new file: .github/prompts/coding-agent-merge-reference-impl-instructions.md new file: .github/scripts/reference-impl-sync/merge-reference-impl-diff.sh new file: .github/scripts/reference-impl-sync/merge-reference-impl-finish.sh new file: .github/scripts/reference-impl-sync/merge-reference-impl-start.sh new file: .github/skills/agentic-merge-reference-impl/SKILL.md new file: .github/workflows/weekly-reference-impl-sync.lock.yml new file: .github/workflows/weekly-reference-impl-sync.md new file: .github/workflows/weekly-reference-impl-sync.yml modified: CONTRIBUTING.md modified: README.md modified: docs/WORKFLOWS.md Signed-off-by: Ed Burns <edburns@microsoft.com>

Rebase the topic branch onto current main and preserve the original intent: replace "upstream" naming with "reference implementation" across the repo. - Update docs, prompts, workflows, and release automation wording - Remove legacy upstream-sync assets superseded by reference-impl-sync assets - Update references in tests and project guidance content - Keep behavior aligned while clarifying terminology - Apply Spotless formatting updates in touched Java test files

Agent-Logs-Url: https://github.com/github/copilot-sdk-java/sessions/dc42a537-067a-4251-bd14-0fb8fede94d9 Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

@Copilot wrote: > This file is runtime-imported by weekly-reference-impl-sync.lock.yml as the agent prompt, but its content is written as documentation rather than imperative agent instructions (e.g., it doesn’t tell the agent to read .lastmerge, clone, compare commits, and must call a safe-output tool). As a result, the agentic workflow may fail or behave unpredictably. Please restore the prior imperative, step-by-step instruction style (like the deleted weekly-upstream-sync.md), updated to the new reference-impl terminology, and ensure it explicitly requires calling create-issue/close-issue/noop as appropriate.

edburns · 2026-04-16T22:51:40Z

@copilot review this PR.

Copilot · 2026-04-16T22:53:38Z

@copilot review this PR.

The PR looks good. Here's a summary of what was reviewed:

Consistency: All occurrences of "upstream" (case-insensitive) across .yml, .md, .sh, and .java files have been replaced — no stragglers remain.

Changelog handling: The update-changelog.sh awk script's skip_old_reference_impl pattern strips > **Reference implementation sync:** lines from the previous [Unreleased] section on each release run. Since CHANGELOG.md was updated in this same PR to use the new terminology, the script will correctly process future releases.

Behavioral changes: None. The renames (workflow files, script files, skill directories, prompt files) are purely cosmetic — schedules, triggers, and logic are unchanged.

Minor observations:

The trailing newline added at the end of publish-maven.yml is a no-op but harmless.
The .gitignore entry for tilde backup files is a good housekeeping addition.

No issues found that require changes.

edburns · 2026-04-16T22:56:54Z

Hello @brunoborges , can you please review #77 ?

It is orthogonal to #69 but still important. More importantly it only has 26 files changed instead of 325!

Copilot

Pull request overview

This PR standardizes repository language by replacing ambiguous “upstream” references with “reference implementation” terminology, clarifying that sync/porting targets the external github/copilot-sdk reference implementation rather than Git branch tracking.

Changes:

Renames/rewrites sync-related docs, prompts, skills, and workflow text from “upstream” to “reference implementation”.
Updates release automation wording to record “reference implementation sync” commit hashes in CHANGELOG.md.
Removes legacy upstream-named agentic workflow/skill assets in favor of reference-impl equivalents.

Show a summary per file

File	Description
src/test/java/com/github/copilot/sdk/HooksTest.java	Updates test Javadoc wording to “reference implementation”.
src/test/java/com/github/copilot/sdk/ElicitationTest.java	Updates porting attribution wording in Javadoc.
src/test/java/com/github/copilot/sdk/CommandsTest.java	Updates porting attribution wording in Javadoc.
docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md	Replaces “upstream” wording in ADR text; minor formatting touch.
docs/adr/adr-001-semver-pre-general-availability.md	Replaces “upstream” wording with “reference implementation”; minor formatting touch.
docs/WORKFLOWS.md	Renames workflow references and describes “reference implementation” sync behavior.
README.md	Updates workflow/sync section terminology and references to new prompt/workflow names.
CONTRIBUTING.md	Updates contributor guidance to distinguish reference implementation vs this repo.
CHANGELOG.md	Renames “Upstream sync” markers and per-item parentheticals to “Reference implementation …”.
.gitignore	Ignores editor backup files (`*~`).
.github/workflows/weekly-upstream-sync.md	Removes the legacy upstream-named agentic workflow source prompt.
.github/workflows/weekly-reference-impl-sync.yml	Updates workflow name/steps/labels/messages to “reference implementation”.
.github/workflows/weekly-reference-impl-sync.md	Adds the reference-impl agentic workflow source prompt (runtime-imported).
.github/workflows/weekly-reference-impl-sync.lock.yml	Updates compiled agentic workflow metadata and runtime import to the new `.md` source.
.github/workflows/publish-maven.yml	Renames variables/messages from upstream to reference-impl for `.lastmerge` injection.
.github/skills/agentic-merge-upstream/SKILL.md	Removes upstream-named skill definition.
.github/skills/agentic-merge-reference-impl/SKILL.md	Adds reference-impl-named skill definition.
.github/scripts/release/update-changelog.sh	Renames script argument/printed text and changelog blockquote marker to reference-impl.
.github/scripts/reference-impl-sync/merge-reference-impl-start.sh	Renames/rewrites helper script text and env vars for reference-impl terminology.
.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh	Updates helper script to use `REFERENCE_IMPL_DIR` and reference-impl wording.
.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh	Updates helper script paths/labels to reference-impl terminology.
.github/prompts/coding-agent-merge-reference-impl-instructions.md	Updates coding-agent instructions to point to reference-impl workflow/prompt/label.
.github/prompts/agentic-merge-reference-impl.prompt.md	Updates the reusable merge prompt wording and script references to reference-impl.
.github/copilot-instructions.md	Updates repo-level Copilot instructions to use “reference implementation” terminology.
.claude/skills/agentic-merge-upstream/SKILL.md	Removes upstream-named Claude skill definition.
.claude/skills/agentic-merge-reference-impl/SKILL.md	Adds reference-impl-named Claude skill definition.

Copilot's findings

Comments suppressed due to low confidence (3)

.github/workflows/weekly-reference-impl-sync.md:89

Step 3b references the refererce-impl-sync label (typo). This won’t match the configured label reference-impl-sync, so the automation would fail to find/close the right issues. Update the label spelling to reference-impl-sync.

1. Search for any open issues with the `refererce-impl-sync` label using the GitHub MCP tools.
2. Close each existing open `refererce-impl-sync` issue using the `close_issue` safe-output tool with a comment: "Superseded by a newer reference implementation sync check."
3. Create a new issue using the `create_issue` safe-output tool with:

.github/workflows/weekly-reference-impl-sync.md:116

This line lists a non-existent skill name agentic-merge-agentic-merge-reference-impl (duplicated prefix). Update it to the intended skill name so the instruction is actionable (likely agentic-merge-reference-impl).

- **Do NOT invoke any skills** such as `agentic-merge-agentic-merge-reference-impl` or `commit-as-pull-request`.
- **Do NOT attempt to merge or port reference implementation changes.** That is done by a separate agent that picks up the issue you create.

.github/prompts/agentic-merge-reference-impl.prompt.md:185

These commands reference LAST_REFERENCE_IMPL_COMMIT, but earlier instructions and the helper scripts use .lastmerge / LAST_MERGE_COMMIT. As written, this variable will be undefined and the commands will fail when copied. Use the same variable name consistently (e.g., LAST_MERGE/LAST_MERGE_COMMIT).

Files reviewed: 25/26 changed files
Comments generated: 3

Copilot · 2026-04-16T22:57:22Z

+safe-outputs:
+  create-issue:
+    title-prefix: "[reference-impl-sync] "
+    assignees: [copilot]


The safe-output create-issue frontmatter sets assignees: [copilot], but the non-agentic workflow and docs use copilot-swe-agent. If copilot isn’t a valid assignee, issue creation will fail or assign the wrong account; consider aligning the assignee here with copilot-swe-agent (or omit assignees if assignment is handled via assign-to-agent).

Suggested change

assignees: [copilot]

assignees: [copilot-swe-agent]

Copilot · 2026-04-16T22:57:23Z

 Chosen option: "Track SemVer of reference implementation, with one exception.", because this enables us to pursue Virtual Threads without delaying the first public release of `copilot-sdk-java`. Also, we're supposed to be aggressively modernizing our customers.

-To some extent, I would use qualifiers to mark a release as having some feature that is awaiting an upstream full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until upstream is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances.
+To some extent, I would use qualifiers to mark a release as having some feature that is awaiting an reference implementation full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until reference implementation is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances.


Grammar: “awaiting an reference implementation full release” should be “awaiting a reference implementation full release”.

Suggested change

To some extent, I would use qualifiers to mark a release as having some feature that is awaiting an reference implementation full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until reference implementation is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances.

To some extent, I would use qualifiers to mark a release as having some feature that is awaiting a reference implementation full release before it goes full ga, i.e you put out 0.1.46-virtualthreads.3 until reference implementation is ready to move to 0.2.0 then you release your virtual threads change and go 0.2.0. So I would make your agreement that your version numbers would match with the exception of qualifiers that you might add in exceptional circumstances.

Copilot · 2026-04-16T22:57:23Z

+git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/refererce-impl
+cd /tmp/gh-aw/agent/refererce-impl


The temp directory path is misspelled as refererce-impl, which will cause the instructions to create/cd into a different (non-existent) folder when followed. Rename it consistently to reference-impl in both the git clone target and the cd command.

This issue also appears in the following locations of the same file:

line 87

line 115

Suggested change

git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/refererce-impl

cd /tmp/gh-aw/agent/refererce-impl

git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/reference-impl

cd /tmp/gh-aw/agent/reference-impl

edburns · 2026-04-16T23:00:41Z

@copilot please apply all of your suggestions during your review that happened around 18:50 EDT today.

Agent-Logs-Url: https://github.com/github/copilot-sdk-java/sessions/b635280e-2e95-4f3d-a5d9-a261f99c6e74 Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Copilot · 2026-04-16T23:02:39Z

@copilot please apply all of your suggestions during your review that happened around 18:50 EDT today.

Applied all three review suggestions in commit 03cfc35:

assignees: [copilot] → assignees: [copilot-swe-agent] in the safe-outputs frontmatter
"awaiting an reference implementation" → "awaiting a reference implementation" (grammar fix in ADR-001)
refererce-impl → reference-impl typo fixed at all four occurrences (lines 62, 63, 87, 88) in weekly-reference-impl-sync.md

edburns · 2026-04-16T23:09:13Z

Thanks so much @brunoborges !

modified: .github/aw/actions-lock.json - Adds new pinned entry for `actions/github-script@v9` (sha `373c709c...`) - Updates `github/gh-aw-actions/setup` pin from `v0.63.1` to `v0.68.3` with new sha modified: .github/workflows/weekly-reference-impl-sync.lock.yml - Regenerated by `gh aw compile` (v0.68.3) from the `.md` source that was hand-edited in PR github#77 without recompiling - Compiler upgraded from v0.51.6 to v0.68.3; schema version v1 to v3 - Frontmatter hash updated to reflect current `.md` content - `create_issue` assignee now correctly reflects `copilot-swe-agent` (was `copilot`) - `assign_to_agent` now includes `model: claude-opus-4.6` - Safe-outputs config updated with new tool entries (`create_report_incomplete_issue`, `report_incomplete`, `noop`) - Action pin references updated to match newer gh-aw-actions versions Signed-off-by: Ed Burns <edburns@microsoft.com>

modified: .github/aw/actions-lock.json - Adds new pinned entry for `actions/github-script@v9` (sha `373c709c...`) - Updates `github/gh-aw-actions/setup` pin from `v0.63.1` to `v0.68.3` with new sha modified: .github/workflows/weekly-reference-impl-sync.lock.yml - Regenerated by `gh aw compile` (v0.68.3) from the `.md` source that was hand-edited in PR #77 without recompiling - Compiler upgraded from v0.51.6 to v0.68.3; schema version v1 to v3 - Frontmatter hash updated to reflect current `.md` content - `create_issue` assignee now correctly reflects `copilot-swe-agent` (was `copilot`) - `assign_to_agent` now includes `model: claude-opus-4.6` - Safe-outputs config updated with new tool entries (`create_report_incomplete_issue`, `report_incomplete`, `noop`) - Action pin references updated to match newer gh-aw-actions versions Signed-off-by: Ed Burns <edburns@microsoft.com> Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

edburns and others added 5 commits April 16, 2026 15:04

Fix [reference-impl-hash] parameter naming in update-changelog.sh

406186b

Agent-Logs-Url: https://github.com/github/copilot-sdk-java/sessions/dc42a537-067a-4251-bd14-0fb8fede94d9 Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Ignore tilde files

e3f246a

edburns self-assigned this Apr 16, 2026

Copilot started work on behalf of edburns April 16, 2026 22:51 View session

edburns marked this pull request as ready for review April 16, 2026 22:53

edburns requested review from brunoborges and Copilot April 16, 2026 22:54

Copilot finished work on behalf of edburns April 16, 2026 22:54

Copilot started reviewing on behalf of edburns April 16, 2026 22:54 View session

Copilot AI reviewed Apr 16, 2026

View reviewed changes

Copilot started work on behalf of edburns April 16, 2026 23:00 View session

Apply review suggestions: fix assignee, grammar, and refererce-impl typo

03cfc35

Agent-Logs-Url: https://github.com/github/copilot-sdk-java/sessions/b635280e-2e95-4f3d-a5d9-a261f99c6e74 Co-authored-by: edburns <75821+edburns@users.noreply.github.com>

Copilot finished work on behalf of edburns April 16, 2026 23:03

brunoborges approved these changes Apr 16, 2026

View reviewed changes

edburns merged commit e4516c8 into main Apr 16, 2026
7 of 8 checks passed

edburns deleted the edburns/dd-2853206-reference-impl-not-upstream branch April 16, 2026 23:09

edburns mentioned this pull request Apr 17, 2026

Add classical code generation workflow for Java SDK and migrate to generated event types #70

Closed

6 tasks

edburns mentioned this pull request Apr 17, 2026

Recompile agentic workflow lock file from updated .md source #78

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace ambiguous upstream terminology with reference implementation wording#77

Replace ambiguous upstream terminology with reference implementation wording#77
edburns merged 6 commits intomainfrom
edburns/dd-2853206-reference-impl-not-upstream

edburns commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

Copilot AI Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		git clone --quiet https://github.com/github/copilot-sdk.git /tmp/gh-aw/agent/refererce-impl
		cd /tmp/gh-aw/agent/refererce-impl

Conversation

edburns commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 16, 2026

Choose a reason for hiding this comment

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Copilot AI commented Apr 16, 2026

Uh oh!

edburns commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants