From 66dfc86f00366c0fe20c12bdf9511e3b851cc7c5 Mon Sep 17 00:00:00 2001 From: Ryan Fitzgerald Date: Wed, 10 Apr 2019 18:22:06 -0700 Subject: [PATCH] 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 --- ReleaseGuidelines.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/ReleaseGuidelines.md b/ReleaseGuidelines.md index 3df33c1e..2481b965 100644 --- a/ReleaseGuidelines.md +++ b/ReleaseGuidelines.md @@ -19,6 +19,26 @@ MDS uses [Semantic Versioning][semver]. Each release is associated with a [`git 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. +### Breaking vs. non-breaking changes + +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. + +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. + +Examples of breaking changes include: + +* Adding or removing a required endpoint or field +* Adding or removing a request parameter +* Changing the data type or semantics of an existing field, including clarifying previously-ambiguous requirements + +Examples of non-breaking changes include: + +* Adding or removing an optional endpoint or field +* Adding or removing enum values +* Modifying documentation or spec language that doesn't affect the behavior of the API directly + +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. + ### Ongoing version support At this early stage, MDS will be moving relatively quickly with an eye toward stabilization rather than backwards-compatibility.