CODEWITHSUNDEEP
javascriptnpmsemantic-versioning
Matthew Mullin
Matthew Mullin

Reputation: 7636

Semantic Versioning (Semver) - How to semver large functional updates that are backwards compatible

My understanding is that using X.Y.Z, we only change X for breaking changes. Y is for backward compatible functional changes.

So am I correct in assuming that even if my update is an absolutely huge addition to functionality - with no breaking changes as it is only an addition, I will still not change the X?

TLDR No matter how 'major' the update, if it is not a breaking change you don't change the X of X.Y.Z?

Upvotes: 5

Views: 956

Answers (1)

Douglas Reid
Douglas Reid

Reputation: 3788

You can increment the major version number for a large functional update that is backwards compatible. I submit that you usually should.

Paragraph 8 of Semver 2.0.0 states:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY include minor and patch level changes. Patch and minor version MUST be reset to 0 when major version is incremented. (Emphasis added.)

Using a strict application of the RFC 2119 terms MAY, MUST, and MUST NOT as incorporated by reference in Semver the emphasized statement means it is permissible, but not required, to increment the major version number when a change includes only minor and patch level changes.

That's what a huge number of non-breaking changes are: a huge number of minor and patch level changes.

Conspicuously absent in this paragraph of the spec are any statements equivalent to:

  • It must not include only minor and patch level changes
  • It must include backwards incompatible changes

Based on paragraph 7 another permissible alternative would be to increment the minor version only in your scenario.

This is good. It allows for some discretion in the situation you're describing where the public API did not technically change in a backwards incompatible way but the changes are substantial enough that it will feel like a major and intrusive change to (presumably human) users and/or developers.

It also allows for the sometimes business/marketing driven need to increment a major version number based on important feature changes rather than the API specification per se.

Upvotes: 4

Related Questions