Repository navigation
docs(review): spell out additive vs breaking changes on the public surface - #83
Merged
Merged
Conversation
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Spell out additive vs breaking changes in the review rules
Section 9 of
.github/code-review/REVIEW.mddefines what breaks this SDK's public surface. Boththe 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
linking, or see a call that works today against the current API fail or behave differently? If
not, the change is additive.
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.
sealedinterface or class. It is the same case as a newenum constant, which this section already treats as not breaking. The new type is listed as
added, and the sealed parent is not changed;
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 asIllegalArgumentException, changes the error a working caller handles. That makes itbreaking, as the
sdkrule set says ("the error type a call raises, throws or returns,changed").
Only
.github/code-review/REVIEW.mdchanges. The rest of the file, the@includeblock and theorder are untouched.
Why now
The API change that turned
dteinto a list, range or comparison is additive for this SDK, andshould be a minor release. The bump was computed as major because of two of these cases:
ExpirationFilter;ExpirationFilter.dte(int)that throwsIllegalArgumentException.With these rules:
dte(int)stays additive only when it fails withBadRequestError, or when themethod 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.