Skip to content
This repository has been archived by the owner on Nov 10, 2022. It is now read-only.

Commit

Permalink
Flesh out definition of breaking vs. non-breaking changes
Browse files Browse the repository at this point in the history
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 openmobilityfoundation#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 openmobilityfoundation#279
  • Loading branch information
rf- committed Apr 16, 2019
1 parent d399ee7 commit 66dfc86
Showing 1 changed file with 20 additions and 0 deletions.
20 changes: 20 additions & 0 deletions ReleaseGuidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit 66dfc86

Please sign in to comment.