Skip to content

docs(review): spell out additive vs breaking changes on the public surface #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarketDataDev03 merged 2 commits into from
Oct 1, 2026
Merged

docs(review): spell out additive vs breaking changes on the public surface #83

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a2d928
docs(review): spell out additive vs breaking changes on the public su…
MarketDataDev03 Oct 1, 2026
ecc1c60
docs(review): tie client-side checks to the error type they raise
MarketDataDev03 Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 23 additions & 3 deletions .github/code-review/REVIEW.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -31,9 +35,25 @@ 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 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
Expand Down
Loading