Replace ambiguous upstream terminology with reference implementation wording#75
Closed
edburns wants to merge 5 commits intogithub:mainfrom
Closed
Replace ambiguous upstream terminology with reference implementation wording#75edburns wants to merge 5 commits intogithub:mainfrom
edburns wants to merge 5 commits intogithub:mainfrom
Conversation
…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
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes repository terminology by replacing ambiguous uses of “upstream” (which has a specific Git meaning) with “reference implementation” when referring to the external github/copilot-sdk project and its commit lineage, across docs, prompts, workflows, and release automation.
Changes:
- Renames “upstream sync/merge” wording (and related labels/asset names) to “reference implementation sync/merge” across documentation and automation.
- Updates weekly sync workflows and the agentic workflow assets to use
reference-impl-syncnaming. - Updates release automation text to record “Reference implementation sync” in the changelog.
Show a summary per file
| File | Description |
|---|---|
| src/test/java/com/github/copilot/sdk/HooksTest.java | Updates test Javadoc to reference “reference implementation” terminology. |
| src/test/java/com/github/copilot/sdk/ElicitationTest.java | Updates test Javadoc wording for reference implementation. |
| src/test/java/com/github/copilot/sdk/CommandsTest.java | Updates test Javadoc wording for reference implementation. |
| docs/adr/adr-002-maven-version-and-reference-implementation-tracking.md | Updates ADR wording to “reference implementation” and minor whitespace. |
| docs/adr/adr-001-semver-pre-general-availability.md | Updates ADR wording to “reference implementation” (introduced a grammar issue). |
| docs/WORKFLOWS.md | Renames weekly sync entries/sections to “reference implementation”. |
| README.md | Renames “Agentic Upstream Merge and Sync” section and references to new workflow/prompt names. |
| CONTRIBUTING.md | Rewords contribution guidance to refer to the reference implementation SDK. |
| CHANGELOG.md | Replaces “Upstream sync” phrasing with “Reference implementation sync” throughout. |
| .github/workflows/weekly-upstream-sync.md | Removes legacy agentic prompt source for upstream sync. |
| .github/workflows/weekly-reference-impl-sync.yml | Renames workflow UI strings and issue label/wording to reference implementation. |
| .github/workflows/weekly-reference-impl-sync.md | Adds new agentic workflow prompt source (currently written as documentation, not agent instructions). |
| .github/workflows/weekly-reference-impl-sync.lock.yml | Updates compiled agentic workflow metadata, names, labels, and runtime-import target. |
| .github/workflows/publish-maven.yml | Rewords release workflow output/comments to “reference implementation” sync hash. |
| .github/skills/agentic-merge-upstream/SKILL.md | Removes legacy upstream merge skill metadata. |
| .github/skills/agentic-merge-reference-impl/SKILL.md | Adds reference-impl merge skill metadata and points to new prompt. |
| .github/scripts/release/update-changelog.sh | Renames “upstream” variables/output to “reference implementation” in changelog injection logic. |
| .github/scripts/reference-impl-sync/merge-reference-impl-start.sh | Renames helper script comments/vars and env exports to reference-impl naming. |
| .github/scripts/reference-impl-sync/merge-reference-impl-finish.sh | Renames helper script comments/vars and label guidance to reference-impl naming. |
| .github/scripts/reference-impl-sync/merge-reference-impl-diff.sh | Renames helper script comments/vars and output text to reference-impl naming. |
| .github/prompts/coding-agent-merge-reference-impl-instructions.md | Updates coding-agent instructions to reference new workflow/prompt and new label name. |
| .github/prompts/agentic-merge-reference-impl.prompt.md | Renames prompt wording from upstream to reference implementation (introduced variable mismatches). |
| .github/copilot-instructions.md | Updates Copilot repo instructions to prefer “reference implementation” terminology. |
| .claude/skills/agentic-merge-upstream/SKILL.md | Removes legacy upstream merge skill metadata. |
| .claude/skills/agentic-merge-reference-impl/SKILL.md | Adds reference-impl merge skill metadata and points to new prompt. |
Copilot's findings
Comments suppressed due to low confidence (2)
.github/prompts/agentic-merge-reference-impl.prompt.md:186
- The instructions here reference shell variables that don’t match the scripts this prompt tells users to run:
merge-reference-impl-start.shwrites.merge-envwithREFERENCE_IMPL_DIRandLAST_MERGE_COMMIT, but this section uses$TEMP_DIRand$LAST_REFERENCE_IMPL_COMMIT. These commands won’t work as written; please update them to use the variables that are actually exported (or adjust the scripts to export the names used here).
.github/prompts/coding-agent-merge-reference-impl-instructions.md:2 - The header comment says this file is read by
.github/workflows/weekly-reference-impl-sync.ymland passed ascustom_instructions, but there are no references to this filename anywhere under.github/workflows/in the repo. Please either wire this file into the workflow (if intended) or update/remove the comment to avoid misleading future maintainers.
- Files reviewed: 25/25 changed files
- Comments generated: 4
Comment on lines
+10
to
+11
| | [Weekly Reference Implementation Sync](workflows/weekly-reference-impl-sync.yml) | Checks for new reference implementation commits and creates an issue for Copilot to merge | `workflow_dispatch` | Mondays at 10:00 UTC | | ||
| | [Weekly Reference Implementation Sync (Agentic)](workflows/weekly-reference-impl-sync.lock.yml) | Compiled agentic workflow that executes the reference implementation sync via `gh-aw` | `workflow_dispatch` | Tuesdays at 08:39 UTC (scattered) | |
There was a problem hiding this comment.
These markdown links point to docs/workflows/..., but there is no docs/workflows directory in the repo, so the links in the overview table will be broken. Please update them to point at the real workflow locations (e.g., ../.github/workflows/weekly-reference-impl-sync.yml and ../.github/workflows/weekly-reference-impl-sync.lock.yml).
| 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. |
There was a problem hiding this comment.
Grammar: this should be "a reference implementation" (not "an reference implementation").
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. |
6 tasks
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.
Collaborator
Author
|
Will re-open from upstream. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This change is not cosmetic pedantry. It removes a source of repeated ambiguity that affects contributors, automation, and review quality.
In Git,
upstreamhas 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:
What this PR does:
This change is deliberately scoped to terminology and clarity. The practical outcome is fewer misunderstandings, safer maintenance, and more accurate communication across the project.