Skip to content

Commit 61eab50

Browse files
brunoborgesbrunoborges
committed
feat: add detailed guidelines for porting upstream SDK changes to Java SDK
1 parent f39fd82 commit 61eab50

File tree

2 files changed

+226
-0
lines changed

2 files changed

+226
-0
lines changed

‎.github/prompts/agentic-merge-upstream.prompt.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
# Merge Upstream SDK Changes
2+
3+
You are an expert Java developer tasked with porting changes from the official Copilot SDK (primarily the .NET implementation) to this Java SDK.
4+
5+
## ⚠️ IMPORTANT: Java SDK Design Takes Priority
6+
7+
**The current design and architecture of the Java SDK is the priority.** When porting changes from upstream:
8+
9+
1. **Adapt, don't copy** - Translate upstream features to fit the Java SDK's existing patterns, naming conventions, and architecture
10+
2. **Preserve Java idioms** - The Java SDK should feel natural to Java developers, not like a C# port
11+
3. **Maintain consistency** - New code must match the existing codebase style and structure
12+
4. **Evaluate before porting** - Not every upstream change needs to be ported; some may not be applicable or may conflict with Java SDK design decisions
13+
14+
Before making any changes, **read and understand the existing Java SDK implementation** to ensure new code integrates seamlessly.
15+
16+
## Workflow Overview
17+
18+
1. Clone upstream repository
19+
2. Analyze diff since last merge
20+
3. Apply changes to Java SDK
21+
4. Test and fix issues
22+
5. Update documentation
23+
6. Leave changes uncommitted for review
24+
25+
---
26+
27+
## Step 1: Clone Upstream Repository
28+
29+
Clone the official Copilot SDK repository into a temporary folder:
30+
31+
```bash
32+
UPSTREAM_REPO="https://github.com/github/copilot-sdk.git"
33+
TEMP_DIR=$(mktemp -d)
34+
git clone --depth=100 "$UPSTREAM_REPO" "$TEMP_DIR/copilot-sdk"
35+
```
36+
37+
## Step 2: Read Last Merge Commit
38+
39+
Read the commit hash from `.lastmerge` file in the Java SDK root:
40+
41+
```bash
42+
LAST_MERGE_COMMIT=$(cat .lastmerge)
43+
echo "Last merged commit: $LAST_MERGE_COMMIT"
44+
```
45+
46+
## Step 3: Analyze Changes
47+
48+
Generate a diff between the last merged commit and HEAD of main:
49+
50+
```bash
51+
cd "$TEMP_DIR/copilot-sdk"
52+
git fetch origin main
53+
git log --oneline "$LAST_MERGE_COMMIT"..origin/main
54+
git diff "$LAST_MERGE_COMMIT"..origin/main --stat
55+
```
56+
57+
Focus on analyzing:
58+
- `dotnet/src/` - Primary reference implementation
59+
- `dotnet/test/` - Test cases to port
60+
- `docs/` - Documentation updates
61+
- `sdk-protocol-version.json` - Protocol version changes
62+
63+
## Step 4: Identify Changes to Port
64+
65+
For each change in the upstream diff, determine:
66+
67+
1. **New Features**: New methods, classes, or capabilities added to the SDK
68+
2. **Bug Fixes**: Corrections to existing functionality
69+
3. **API Changes**: Changes to public interfaces or method signatures
70+
4. **Protocol Updates**: Changes to the JSON-RPC protocol or message types
71+
5. **Test Updates**: New or modified test cases
72+
73+
### Key Files to Compare
74+
75+
| Upstream (.NET) | Java SDK Equivalent |
76+
|------------------------------------|--------------------------------------------------------|
77+
| `dotnet/src/Client.cs` | `src/main/java/com/github/copilot/sdk/CopilotClient.java` |
78+
| `dotnet/src/Session.cs` | `src/main/java/com/github/copilot/sdk/CopilotSession.java` |
79+
| `dotnet/src/Types.cs` | `src/main/java/com/github/copilot/sdk/types/*.java` |
80+
| `dotnet/src/Generated/*.cs` | `src/main/java/com/github/copilot/sdk/types/*.java` |
81+
| `dotnet/test/*.cs` | `src/test/java/com/github/copilot/sdk/*Test.java` |
82+
| `docs/getting-started.md` | `README.md` and `src/site/markdown/*.md` |
83+
| `sdk-protocol-version.json` | (embedded in Java code or resource file) |
84+
85+
## Step 5: Apply Changes to Java SDK
86+
87+
When porting changes:
88+
89+
### ⚠️ Priority: Preserve Java SDK Design
90+
91+
Before modifying any code:
92+
93+
1. **Read the existing Java implementation first** - Understand current patterns, class structure, and naming
94+
2. **Identify the Java equivalent approach** - Don't replicate C# patterns; find the idiomatic Java way
95+
3. **Check for existing abstractions** - The Java SDK may already have mechanisms that differ from .NET
96+
4. **Preserve backward compatibility** - Existing API signatures should not break unless absolutely necessary
97+
5. **When in doubt, match existing code** - Follow what's already in the Java SDK, not the upstream
98+
99+
### General Guidelines
100+
101+
- **Naming Conventions**: Convert C# PascalCase to Java camelCase for methods/variables
102+
- **Async Patterns**: C# `async/await` → Java `CompletableFuture` or synchronous equivalents
103+
- **Nullable Types**: C# `?` nullable → Java `@Nullable` annotations or `Optional<T>`
104+
- **Properties**: C# properties → Java getters/setters or records
105+
- **Records**: C# records → Java records (Java 17+)
106+
- **Events**: C# events → Java callbacks or listeners
107+
108+
### Type Mappings
109+
110+
| C# Type | Java Equivalent |
111+
|------------------------|------------------------------|
112+
| `string` | `String` |
113+
| `int` | `int` / `Integer` |
114+
| `bool` | `boolean` / `Boolean` |
115+
| `Task<T>` | `CompletableFuture<T>` |
116+
| `CancellationToken` | (custom implementation) |
117+
| `IAsyncEnumerable<T>` | `Stream<T>` or `Iterator<T>` |
118+
| `JsonElement` | `JsonNode` (Jackson) |
119+
| `Dictionary<K,V>` | `Map<K,V>` |
120+
| `List<T>` | `List<T>` |
121+
122+
### Code Style
123+
124+
Follow the existing Java SDK patterns:
125+
- Use Jackson for JSON serialization (`ObjectMapper`)
126+
- Use Java records for DTOs where appropriate
127+
- Follow the existing package structure under `com.github.copilot.sdk`
128+
- Maintain backward compatibility when possible
129+
- **Match the style of surrounding code** - Consistency with existing code is more important than upstream patterns
130+
- **Prefer existing abstractions** - If the Java SDK already solves a problem differently than .NET, keep the Java approach
131+
132+
## Step 6: Format and Run Tests
133+
134+
After applying changes, format the code and run the test suite:
135+
136+
```bash
137+
mvn spotless:apply
138+
mvn clean test
139+
```
140+
141+
**Important:** Always run `mvn spotless:apply` before testing to ensure code formatting is consistent with project standards.
142+
143+
### If Tests Fail
144+
145+
1. Read the test output carefully
146+
2. Identify the root cause (compilation error, runtime error, assertion failure)
147+
3. Fix the issue in the Java code
148+
4. Re-run tests
149+
5. Repeat until all tests pass
150+
151+
### Common Issues
152+
153+
- **Missing imports**: Add required import statements
154+
- **Type mismatches**: Ensure proper type conversions
155+
- **Null handling**: Add null checks where C# had nullable types
156+
- **JSON serialization**: Verify Jackson annotations are correct
157+
158+
## Step 7: Build the Package
159+
160+
Once tests pass, build the complete package:
161+
162+
```bash
163+
mvn clean package -DskipTests
164+
```
165+
166+
Verify:
167+
- No compilation errors
168+
- No warnings (if possible)
169+
- JAR file is generated in `target/`
170+
171+
## Step 8: Update Documentation
172+
173+
Review and update documentation as needed:
174+
175+
1. **README.md**: Update if there are new features or API changes
176+
2. **src/site/markdown/documentation.md**: Update detailed documentation
177+
3. **Javadoc**: Add/update Javadoc comments for new/changed public APIs
178+
4. **CHANGELOG**: (if exists) Add entry for the changes
179+
180+
## Step 9: Update Last Merge Reference
181+
182+
Update the `.lastmerge` file with the new HEAD commit:
183+
184+
```bash
185+
cd "$TEMP_DIR/copilot-sdk"
186+
NEW_COMMIT=$(git rev-parse origin/main)
187+
echo "$NEW_COMMIT" > /.lastmerge
188+
```
189+
190+
## Step 10: Final Review (DO NOT COMMIT)
191+
192+
Before finishing:
193+
194+
1. Run `git status` to see all changed files
195+
2. Run `git diff` to review all changes
196+
3. Ensure no unintended changes were made
197+
4. Verify code follows project conventions
198+
5. **DO NOT COMMIT** - leave changes staged/unstaged for user review
199+
200+
---
201+
202+
## Checklist
203+
204+
- [ ] Upstream repository cloned
205+
- [ ] Diff analyzed between `.lastmerge` commit and HEAD
206+
- [ ] New features/fixes identified
207+
- [ ] Changes ported to Java SDK following conventions
208+
- [ ] `mvn test` passes
209+
- [ ] `mvn package` builds successfully
210+
- [ ] Documentation updated
211+
- [ ] `.lastmerge` file updated with new commit hash
212+
- [ ] Changes left uncommitted for review
213+
214+
---
215+
216+
## Notes
217+
218+
- The upstream SDK is at: `https://github.com/github/copilot-sdk.git`
219+
- Primary reference implementation is in `dotnet/` folder
220+
- This Java SDK targets Java 17+
221+
- Uses Jackson for JSON processing
222+
- Uses JUnit 5 for testing
223+
- **Java SDK design decisions take precedence over upstream patterns**
224+
- **Adapt upstream changes to fit Java idioms, not the other way around**
225+

‎.lastmerge‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
7a3dcf3d3f61bdc87bf860055346156cbe405172

0 commit comments

Comments
 (0)