From 69f20998a0980f2c963fbcc1db654c0c2de33aab Mon Sep 17 00:00:00 2001 From: Ed Burns Date: Tue, 24 Feb 2026 16:52:33 -0500 Subject: [PATCH 1/2] On branch edburns/dd-2745172-adr-001-virtual-threads-plan modified: .gitignore - Ignore Claude worktrees. new file: docs/adr/adr-001-semver-pre-general-availability.md - ADR for JDK 21 decision. Signed-off-by: Ed Burns --- .gitignore | 3 ++- ...adr-001-semver-pre-general-availability.md | 27 +++++++++++++++++++ 2 files changed, 29 insertions(+), 1 deletion(-) create mode 100644 docs/adr/adr-001-semver-pre-general-availability.md diff --git a/.gitignore b/.gitignore index 37e4620a8..5f035eaa5 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ target examples-test/ .merge-env -blog-copilotsdk/ \ No newline at end of file +blog-copilotsdk/ +.claude/worktrees diff --git a/docs/adr/adr-001-semver-pre-general-availability.md b/docs/adr/adr-001-semver-pre-general-availability.md new file mode 100644 index 000000000..4be3fa566 --- /dev/null +++ b/docs/adr/adr-001-semver-pre-general-availability.md @@ -0,0 +1,27 @@ +# SemVer requirements pre general-availability of Reference Implementation + +## Context and Problem Statement + +Steve Sanderson agreed that `copilot-sdk-java` will track reference implementation version numbers directly, with one exception: when the Java SDK needs to ship a breaking change before 1.0, the reference implementation will bump its minor version to accommodate, giving our release a clean version number that signals the change to users. + +The reference implementation makes no backward compatibility guarantees pre-1.0 — and neither will we. That said, we're choosing to hold ourselves to a higher standard as a matter of good practice: we'll use minor version bumps as a signal to users when we do ship something breaking. + +The 2026-02 state of `copilot-sdk-java` is that it takes Java 17+ as its baseline. This decision precludes the use of Java 21 features such as virtual threads. Our pre-analisys showed the **possibility** of a significant performance benefit when using Virtual Threads with Java 21. + +We took an architectural decision to enable us to pursue investigating this possibility immediately. + +## Considered Options + +* Track SemVer of reference implementation, with one exception. +* Completely avoid the need for this by doing no breaking changes pre-1.0. +* Abandon the policy of tracking the versions of the reference implementation directly, just do our own thing. + +## Decision Outcome + +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. + +## Related work items + +- https://devdiv.visualstudio.com/DevDiv/_workitems/edit/2745172 From 309821597dfcadfdee9f67978d37ae79ac8710ce Mon Sep 17 00:00:00 2001 From: Bruno Borges Date: Tue, 24 Feb 2026 17:04:31 -0500 Subject: [PATCH 2/2] Update docs/adr/adr-001-semver-pre-general-availability.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/adr/adr-001-semver-pre-general-availability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/adr-001-semver-pre-general-availability.md b/docs/adr/adr-001-semver-pre-general-availability.md index 4be3fa566..44c9cf6db 100644 --- a/docs/adr/adr-001-semver-pre-general-availability.md +++ b/docs/adr/adr-001-semver-pre-general-availability.md @@ -6,7 +6,7 @@ Steve Sanderson agreed that `copilot-sdk-java` will track reference implementati The reference implementation makes no backward compatibility guarantees pre-1.0 — and neither will we. That said, we're choosing to hold ourselves to a higher standard as a matter of good practice: we'll use minor version bumps as a signal to users when we do ship something breaking. -The 2026-02 state of `copilot-sdk-java` is that it takes Java 17+ as its baseline. This decision precludes the use of Java 21 features such as virtual threads. Our pre-analisys showed the **possibility** of a significant performance benefit when using Virtual Threads with Java 21. +The 2026-02 state of `copilot-sdk-java` is that it takes Java 17+ as its baseline. This decision precludes the use of Java 21 features such as virtual threads. Our pre-analysis showed the **possibility** of a significant performance benefit when using Virtual Threads with Java 21. We took an architectural decision to enable us to pursue investigating this possibility immediately.