Skip to content

Commit 66dfc86

Browse files
committed
Flesh out definition of breaking vs. non-breaking changes
This commit adds a section to the release guidelines doc clarifying the distinction between breaking and non-breaking changes, including an enumeration of what kinds of changes fall in each category. This builds on language added in #286; I didn't modify those templates here since their description of breaking vs. non-breaking is still accurate. I think the most likely area of controversy here is the handling of enum values. My inclination would actually be to treat changes to enum values as breaking changes, but it seems like the consensus during the 0.3.1 process so far has been that the benefits of having a lightweight process for updating enums outweigh the risk of breaking clients that are doing stricter validations. Fixes #279
1 parent d399ee7 commit 66dfc86

1 file changed

Lines changed: 20 additions & 0 deletions

File tree

ReleaseGuidelines.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,26 @@ MDS uses [Semantic Versioning][semver]. Each release is associated with a [`git
1919

2020
Given that MDS is stabilizing under MAJOR version `0.x` right now, it should be assumed that MINOR version increments (e.g. `0.2.0` to `0.3.0`) are equivalent to MAJOR version increments and may contain breaking changes.
2121

22+
### Breaking vs. non-breaking changes
23+
24+
Since MDS is used by a broad ecosystem of both API consumers and implementers, it needs a strict definition of what changes are “non-breaking” and are therefore allowed in PATCH releases.
25+
26+
In the MDS spec, a breaking change is any change that requires either consumers or implementers to modify their code for it to continue to function correctly.
27+
28+
Examples of breaking changes include:
29+
30+
* Adding or removing a required endpoint or field
31+
* Adding or removing a request parameter
32+
* Changing the data type or semantics of an existing field, including clarifying previously-ambiguous requirements
33+
34+
Examples of non-breaking changes include:
35+
36+
* Adding or removing an optional endpoint or field
37+
* Adding or removing enum values
38+
* Modifying documentation or spec language that doesn't affect the behavior of the API directly
39+
40+
One implication of this policy is that clients should be prepared to ignore the presence of unexpected fields in responses and unexpected values for enums. This is necessary to preserve compatibility between PATCH versions within the same MINOR version range, since optional fields and enum values can be added as non-breaking changes.
41+
2242
### Ongoing version support
2343

2444
At this early stage, MDS will be moving relatively quickly with an eye toward stabilization rather than backwards-compatibility.

0 commit comments

Comments
 (0)