Skip to content

Commit 29a3c2c

Browse files
edburnsedburns
committed
On branch edburns/dd-2853206-reference-impl-not-upstream We are tracking 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>
1 parent db56504 commit 29a3c2c

File tree

14 files changed

+2301
-21
lines changed

14 files changed

+2301
-21
lines changed

‎.claude/skills/agentic-merge-reference-impl/SKILL.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
name: agentic-merge-reference-impl
3+
description: Merge reference implementation changes from the official Copilot SDK into this Java SDK.
4+
license: MIT
5+
---
6+
7+
Follow instructions in the [agentic-merge-reference-impl prompt](../../../.github/prompts/agentic-merge-reference-impl.prompt.md) to merge reference implementation changes from the official Copilot SDK into this Java SDK.

‎.github/copilot-instructions.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -89,9 +89,9 @@ Tests use the official copilot-sdk test harness from `https://github.com/github/
8989

9090
## Key Conventions
9191

92-
### Upstream Merging
92+
### Reference Implementation Merging
9393

94-
This SDK tracks the official .NET implementation at `github/copilot-sdk`. The `.lastmerge` file contains the last merged upstream commit hash. Use the `agentic-merge-upstream` skill (see `.github/prompts/agentic-merge-upstream.prompt.md`) to port changes.
94+
This SDK tracks the official .NET implementation at `github/copilot-sdk`. The `.lastmerge` file contains the last merged reference implementation commit hash. Use the `agentic-merge-reference-impl` skill (see `.github/prompts/agentic-merge-reference-impl.prompt.md`) to port changes.
9595

9696
When porting from .NET:
9797
- Adapt to Java idioms, don't copy C# patterns directly
@@ -278,7 +278,7 @@ The repository has a pre-commit hook (`.githooks/pre-commit`) that is **automati
278278
- Include tests for new functionality
279279
- Update documentation if adding/changing public APIs
280280
- Reference related issues using `#issue-number`
281-
- For upstream merges, follow the `agentic-merge-upstream` skill workflow
281+
- For reference implementation merges, follow the `agentic-merge-reference-impl` skill workflow
282282

283283
## Development Workflow
284284

@@ -301,7 +301,7 @@ The release process is automated via the `publish-maven.yml` GitHub Actions work
301301
- Updates version comparison links at the bottom of CHANGELOG.md
302302
- Injects the upstream SDK commit hash (from `.lastmerge`) as a `> **Upstream sync:**` blockquote in both the new `[Unreleased]` section and the released version section
303303

304-
2. **Upstream Sync Tracking**: Each release records which commit from the official `github/copilot-sdk` it is synced to:
304+
2. **Reference Implementation Sync Tracking**: Each release records which commit from the official `github/copilot-sdk` it is synced to:
305305
- The `.lastmerge` file is read during the release workflow
306306
- The commit hash is injected into `CHANGELOG.md` under the release heading
307307
- Format: `> **Upstream sync:** [\`github/copilot-sdk@SHORT_HASH\`](link-to-commit)`

‎.github/prompts/agentic-merge-reference-impl.prompt.md‎

Lines changed: 439 additions & 0 deletions
Large diffs are not rendered by default.

‎.github/prompts/coding-agent-merge-reference-impl-instructions.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<!-- Custom instructions for the Copilot coding agent when triggered by the weekly reference implementation sync workflow. -->
2+
<!-- This file is read by .github/workflows/weekly-reference-impl-sync.yml and passed as custom_instructions. -->
3+
4+
Follow the agentic-merge-reference-impl prompt at .github/prompts/agentic-merge-reference-impl.prompt.md
5+
to port reference implementation changes to the Java SDK.
6+
7+
Use the utility scripts in .github/scripts/ subfolders for initialization, diffing, formatting, and testing.
8+
Commit changes incrementally. Update .lastmerge when done.
9+
10+
IMPORTANT: A pull request has already been created automatically for you — do NOT create a new
11+
one. Push your commits to the current branch, and the existing PR will be updated.
12+
13+
Add the 'reference-impl-sync' label to the existing PR by running this command in a terminal:
14+
15+
gh pr edit --add-label "reference-impl-sync"
16+
17+
If after analyzing the reference implementation diff there are no relevant changes to port to the Java SDK,
18+
push an empty commit with a message explaining why no changes were needed, so the PR reflects
19+
the analysis outcome. The repository maintainer will close the PR and issue manually.

‎.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
#!/usr/bin/env bash
2+
# ──────────────────────────────────────────────────────────────
3+
# merge-reference-impl-diff.sh
4+
#
5+
# Generates a detailed diff analysis of reference implementation changes since
6+
# the last merge, grouped by area of interest:
7+
# • .NET source (primary reference)
8+
# • .NET tests
9+
# • Test snapshots
10+
# • Documentation
11+
# • Protocol / config files
12+
#
13+
# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh [--full]
14+
# --full Show actual diffs, not just stats
15+
#
16+
# Requires: .merge-env written by merge-reference-impl-start.sh
17+
# ──────────────────────────────────────────────────────────────
18+
set -euo pipefail
19+
20+
ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
21+
ENV_FILE="$ROOT_DIR/.merge-env"
22+
23+
if [[ ! -f "$ENV_FILE" ]]; then
24+
echo "❌ $ENV_FILE not found. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh first."
25+
exit 1
26+
fi
27+
28+
# shellcheck source=/dev/null
29+
source "$ENV_FILE"
30+
31+
SHOW_FULL=false
32+
if [[ "${1:-}" == "--full" ]]; then
33+
SHOW_FULL=true
34+
fi
35+
36+
cd "$REFERENCE_IMPL_DIR"
37+
git fetch origin main 2>/dev/null
38+
39+
RANGE="$LAST_MERGE_COMMIT..origin/main"
40+
41+
echo "════════════════════════════════════════════════════════════"
42+
echo " Reference implementation diff analysis: $RANGE"
43+
echo "════════════════════════════════════════════════════════════"
44+
45+
# ── Commit log ────────────────────────────────────────────────
46+
echo ""
47+
echo "── Commit log ──"
48+
git log --oneline --no-decorate "$RANGE"
49+
echo ""
50+
51+
# Helper to print a section
52+
section() {
53+
local title="$1"; shift
54+
local paths=("$@")
55+
56+
echo "── $title ──"
57+
local stat
58+
stat=$(git diff "$RANGE" --stat -- "${paths[@]}" 2>/dev/null || true)
59+
if [[ -z "$stat" ]]; then
60+
echo " (no changes)"
61+
else
62+
echo "$stat"
63+
if $SHOW_FULL; then
64+
echo ""
65+
git diff "$RANGE" -- "${paths[@]}" 2>/dev/null || true
66+
fi
67+
fi
68+
echo ""
69+
}
70+
71+
# ── Sections ──────────────────────────────────────────────────
72+
section ".NET source (dotnet/src)" "dotnet/src/"
73+
section ".NET tests (dotnet/test)" "dotnet/test/"
74+
section "Test snapshots" "test/snapshots/"
75+
section "Documentation (docs/)" "docs/"
76+
section "Protocol & config" "sdk-protocol-version.json" "package.json" "justfile"
77+
section "Go SDK" "go/"
78+
section "Node.js SDK" "nodejs/"
79+
section "Python SDK" "python/"
80+
section "Other files" "README.md" "CONTRIBUTING.md" "SECURITY.md" "SUPPORT.md"
81+
82+
echo "════════════════════════════════════════════════════════════"
83+
echo " To see full diffs: $0 --full"
84+
echo " To see a specific path:"
85+
echo " cd $REFERENCE_IMPL_DIR && git diff $RANGE -- <path>"
86+
echo "════════════════════════════════════════════════════════════"

‎.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
#!/usr/bin/env bash
2+
# ──────────────────────────────────────────────────────────────
3+
# merge-reference-impl-finish.sh
4+
#
5+
# Finalises a reference implementation merge:
6+
# 1. Runs format + test + build (via format-and-test.sh)
7+
# 2. Updates .lastmerge to reference implementation HEAD
8+
# 3. Commits the .lastmerge update
9+
# 4. Pushes the branch to origin
10+
#
11+
# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh
12+
# ./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh --skip-tests
13+
#
14+
# Requires: .merge-env written by merge-reference-impl-start.sh
15+
# ──────────────────────────────────────────────────────────────
16+
set -euo pipefail
17+
18+
ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
19+
ENV_FILE="$ROOT_DIR/.merge-env"
20+
21+
if [[ ! -f "$ENV_FILE" ]]; then
22+
echo "❌ $ENV_FILE not found. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh first."
23+
exit 1
24+
fi
25+
26+
# shellcheck source=/dev/null
27+
source "$ENV_FILE"
28+
29+
SKIP_TESTS=false
30+
if [[ "${1:-}" == "--skip-tests" ]]; then
31+
SKIP_TESTS=true
32+
fi
33+
34+
cd "$ROOT_DIR"
35+
36+
# ── 1. Format, test, build ───────────────────────────────────
37+
if $SKIP_TESTS; then
38+
echo "▸ Formatting only (tests skipped)…"
39+
mvn spotless:apply
40+
mvn clean package -DskipTests
41+
else
42+
echo "▸ Running format + test + build…"
43+
"$ROOT_DIR/.github/scripts/build/format-and-test.sh"
44+
fi
45+
46+
# ── 2. Update .lastmerge ─────────────────────────────────────
47+
echo "▸ Updating .lastmerge…"
48+
NEW_COMMIT=$(cd "$REFERENCE_IMPL_DIR" && git rev-parse origin/main)
49+
echo "$NEW_COMMIT" > "$ROOT_DIR/.lastmerge"
50+
51+
git add .lastmerge
52+
git commit -m "Update .lastmerge to $NEW_COMMIT"
53+
54+
# ── 3. Push branch ───────────────────────────────────────────
55+
echo "▸ Pushing branch $BRANCH_NAME to origin…"
56+
git push -u origin "$BRANCH_NAME"
57+
58+
echo ""
59+
echo "✅ Branch pushed. Next step:"
60+
echo " Create a Pull Request (base: main, head: $BRANCH_NAME)"
61+
echo ""
62+
echo " Suggested title: Merge reference implementation SDK changes ($(date +%Y-%m-%d))"
63+
echo " Don't forget to add the 'reference-impl-sync' label."

‎.github/scripts/reference-impl-sync/merge-reference-impl-start.sh‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
#!/usr/bin/env bash
2+
# ──────────────────────────────────────────────────────────────
3+
# merge-reference-impl-start.sh
4+
#
5+
# Prepares the workspace for a reference implementation merge:
6+
# 1. Creates a dated branch from main
7+
# 2. Updates Copilot CLI and records the new version
8+
# 3. Clones the reference implementation copilot-sdk repo into a temp dir
9+
# 4. Reads .lastmerge and prints a short summary of new commits
10+
#
11+
# Usage: ./.github/scripts/reference-impl-sync/merge-reference-impl-start.sh
12+
# Output: Exports REFERENCE_IMPL_DIR and LAST_MERGE_COMMIT to a
13+
# .merge-env file so other scripts can source it.
14+
# ──────────────────────────────────────────────────────────────
15+
set -euo pipefail
16+
17+
ROOT_DIR="$(cd "$(dirname "$0")/../../.." && pwd)"
18+
cd "$ROOT_DIR"
19+
20+
REFERENCE_IMPL_REPO="https://github.com/github/copilot-sdk.git"
21+
ENV_FILE="$ROOT_DIR/.merge-env"
22+
23+
# ── 1. Create branch (or reuse existing) ─────────────────────
24+
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
25+
26+
if [[ "$CURRENT_BRANCH" != "main" ]]; then
27+
# Already on a non-main branch (e.g., coding agent's auto-created PR branch).
28+
# Stay on this branch — do not create a new one.
29+
BRANCH_NAME="$CURRENT_BRANCH"
30+
echo "▸ Already on branch '$BRANCH_NAME' — reusing it (coding agent mode)."
31+
git pull origin main --no-edit 2>/dev/null || echo " (pull from main skipped or fast-forward not possible)"
32+
else
33+
echo "▸ Ensuring main is up to date…"
34+
git pull origin main
35+
36+
BRANCH_NAME="merge-reference-impl-$(date +%Y%m%d)"
37+
echo "▸ Creating branch: $BRANCH_NAME"
38+
git checkout -b "$BRANCH_NAME"
39+
fi
40+
41+
# ── 2. Update Copilot CLI ────────────────────────────────────
42+
echo "▸ Updating Copilot CLI…"
43+
if command -v copilot &>/dev/null; then
44+
copilot update || echo " (copilot update returned non-zero – check manually)"
45+
CLI_VERSION=$(copilot --version | head -n 1 | awk '{print $NF}')
46+
echo " Copilot CLI version: $CLI_VERSION"
47+
else
48+
echo " ⚠ 'copilot' command not found – skipping CLI update."
49+
CLI_VERSION="UNKNOWN"
50+
fi
51+
52+
# ── 3. Clone reference implementation ────────────────────────────────────────
53+
TEMP_DIR=$(mktemp -d)
54+
REFERENCE_IMPL_DIR="$TEMP_DIR/copilot-sdk"
55+
echo "▸ Cloning reference implementation into $REFERENCE_IMPL_DIR …"
56+
git clone --depth=200 "$REFERENCE_IMPL_REPO" "$REFERENCE_IMPL_DIR"
57+
58+
# ── 4. Read last merge commit ────────────────────────────────
59+
if [[ ! -f "$ROOT_DIR/.lastmerge" ]]; then
60+
echo "❌ .lastmerge file not found in repo root."
61+
exit 1
62+
fi
63+
LAST_MERGE_COMMIT=$(tr -d '[:space:]' < "$ROOT_DIR/.lastmerge")
64+
echo "▸ Last merged reference implementation commit: $LAST_MERGE_COMMIT"
65+
66+
# Quick summary
67+
echo ""
68+
echo "── Reference implementation commits since last merge ──"
69+
(cd "$REFERENCE_IMPL_DIR" && git fetch origin main && \
70+
git log --oneline "$LAST_MERGE_COMMIT"..origin/main) || \
71+
echo " (could not generate log – the commit may have been rebased)"
72+
echo ""
73+
74+
# ── 5. Write env file for other scripts ──────────────────────
75+
cat > "$ENV_FILE" <<EOF
76+
# Auto-generated by merge-reference-impl-start.sh – do not commit
77+
BRANCH_NAME=$BRANCH_NAME
78+
REFERENCE_IMPL_DIR=$REFERENCE_IMPL_DIR
79+
LAST_MERGE_COMMIT=$LAST_MERGE_COMMIT
80+
CLI_VERSION=$CLI_VERSION
81+
EOF
82+
83+
echo "▸ Env file written to $ENV_FILE (sourced by other merge scripts)."
84+
echo ""
85+
echo "✅ Ready. Next steps:"
86+
echo " 1. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-diff.sh to see the full diff analysis."
87+
echo " 2. Port changes to the Java SDK."
88+
echo " 3. Run ./.github/scripts/reference-impl-sync/merge-reference-impl-finish.sh when done."

‎.github/skills/agentic-merge-reference-impl/SKILL.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
name: agentic-merge-reference-impl
3+
description: Merge reference implementation changes from the official Copilot SDK into this Java SDK.
4+
license: MIT
5+
---
6+
7+
Follow instructions in the [agentic-merge-reference-impl prompt](../../prompts/agentic-merge-reference-impl.prompt.md) to merge reference implementation changes from the official Copilot SDK into this Java SDK.

0 commit comments

Comments
 (0)