Skip to content

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

Merged
MarketDataDev03 merged 2 commits into
mainfrom
docs/review-surface-rules
Oct 1, 2026
Merged

MarketDataDev03 merged 2 commits into
mainfrom
docs/review-surface-rules

Conversation

@MarketDataDev03

Copy link
Copy Markdown
Collaborator

Spell out additive vs breaking changes in the review rules

Section 9 of .github/code-review/REVIEW.md defines what breaks this SDK's public surface. Both
the organization's code review bot and the SDK sync pipeline read it to compute the version bump.
Three cases were open to opposite readings, and the same additive API change was computed as a
major bump.

What changes

  • The deciding question opens the section: 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.
  • Breaking, added: a change in behaviour that makes a call that works today fail or return
    something different. For example, a default value changed, a field dropped from a response
    model, or a value the API accepts that the SDK now rejects.
  • Not breaking, now a list, with three new cases:
    • a new permitted subtype of a sealed interface or class. It is the same case as a new
      enum constant, which this section already treats as not breaking. The new type is listed as
      added, and the sealed parent is not changed;
    • a client-side check on a new method or type;
    • a new client-side check on an existing method that only rejects values the current API
      already rejects. This is not breaking only when the check fails with the error type the API's
      rejection already produces (BadRequestError). Any other type, such as
      IllegalArgumentException, changes the error a working caller handles. That makes it
      breaking, as the sdk rule set says ("the error type a call raises, throws or returns,
      changed").

Only .github/code-review/REVIEW.md changes. The rest of the file, the @include block and the
order are untouched.

Why now

The API change that turned dte into a list, range or comparison is additive for this SDK, and
should be a minor release. The bump was computed as major because of two of these cases:

  • new variants of ExpirationFilter;
  • an upper bound added to ExpirationFilter.dte(int) that throws IllegalArgumentException.

With these rules:

  • the variants are additive;
  • a bound on dte(int) stays additive only when it fails with BadRequestError, or when the
    method is left as it was and the API rejects the value.

The review rules apply once this is on main: the bot reads them from the base branch.

…rface

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.
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.
@MarketDataDev03
MarketDataDev03 merged commit d744f98 into main Oct 1, 2026
7 checks passed
@MarketDataDev03
MarketDataDev03 deleted the docs/review-surface-rules branch October 1, 2026 18:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant