From 8a2d928cd2a8c18bc3c65b275044df67995131be Mon Sep 17 00:00:00 2001 From: MarketDataDev03 Date: Thu, 1 Oct 2026 12:47:27 -0400 Subject: [PATCH 1/2] docs(review): spell out additive vs breaking changes on the public surface Open section 9 with the deciding question: does an existing caller stop compiling, stop linking, or see a working call fail or behave differently. List behaviour changes that break working calls as breaking. List a new permitted subtype of a sealed type, and a client-side check that only rejects values the API already rejects, as not breaking, so these cases are not read as a major bump. --- .github/code-review/REVIEW.md | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/.github/code-review/REVIEW.md b/.github/code-review/REVIEW.md index 83af2e1..ab308a8 100644 --- a/.github/code-review/REVIEW.md +++ b/.github/code-review/REVIEW.md @@ -3,6 +3,10 @@ ## 9. The public surface of this SDK +One question decides: does an existing caller stop compiling, stop linking, or +see a call that works today against the current API fail or behave +differently? If not, the change is additive and is not breaking. + The surface is every `public` and `protected` type, method, constructor and field under `src/main/java`. The artifact is published to Maven Central as `app.marketdata`, and it is idiomatic from both Java and Kotlin, so a change @@ -31,9 +35,21 @@ Breaking, for this SDK: - a return type changed at all, widened included. The return type is part of the method descriptor, so existing compiled callers stop linking - -Not breaking: a new overload, a new `default` interface method, a new type, a -new enum constant at the end of the list. +- a change in behaviour that makes a call that works today against the current + API fail, or return something different: a default value changed, a field + dropped from a response model, a value the API accepts that the SDK now + rejects + +Not breaking: + +- a new overload, a new `default` interface method, a new type, a new enum + constant at the end of the list +- a new permitted subtype of a `sealed` interface or class, which is the same + case as a new enum constant: an exhaustive `switch` or `when` gains a case to + handle. List the new type as added; the sealed parent is not changed +- a new client-side check that only rejects values the current API already + rejects: no call that works today stops working. It goes in the CHANGELOG + under `### Changed`, not as a break The version comes from the `sdkVersion` Gradle property at release time, not from a file in the tree. The bump is therefore declared in `CHANGELOG.md` and in From ecc1c60935592749f45de1535548598100bff99e Mon Sep 17 00:00:00 2001 From: MarketDataDev03 Date: Thu, 1 Oct 2026 14:09:24 -0400 Subject: [PATCH 2/2] docs(review): tie client-side checks to the error type they raise A new check on an existing method that rejects values the API already rejects is additive only when it fails with the same error type as the API's rejection, BadRequestError. Any other type changes the error a working caller handles, which the sdk rule set counts as breaking. A check on a new method or type has no existing call to break. --- .github/code-review/REVIEW.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/.github/code-review/REVIEW.md b/.github/code-review/REVIEW.md index ab308a8..629616a 100644 --- a/.github/code-review/REVIEW.md +++ b/.github/code-review/REVIEW.md @@ -47,9 +47,13 @@ Not breaking: - a new permitted subtype of a `sealed` interface or class, which is the same case as a new enum constant: an exhaustive `switch` or `when` gains a case to handle. List the new type as added; the sealed parent is not changed -- a new client-side check that only rejects values the current API already - rejects: no call that works today stops working. It goes in the CHANGELOG - under `### Changed`, not as a break +- a client-side check on a new method or type: there is no existing call to + break +- a new client-side check on an existing method that only rejects values the + current API already rejects, only if it fails with the error type the API's + rejection already produces (`BadRequestError`). Failing with any other type, + such as `IllegalArgumentException`, changes the error a working caller + handles, and is breaking The version comes from the `sdkVersion` Gradle property at release time, not from a file in the tree. The bump is therefore declared in `CHANGELOG.md` and in