semver: v1 vs v1000

Gajus Kuizinas - Apr 6 '22 - - Dev Community

It's something that keeps coming up in GitHub issues on my various projects... they point at my project version, which could be v7, v28, v33, and then say "This project versioning is bad." or "This project API is unstable.", etc. and then compare them to projects that are v1, as if that somehow proves their point.

Here is the thing: any change that may break someone's project by merely upgrading your dependency is a breaking change and requires that you bump the major version. This includes:

  • dropping Node.js version support
  • removing Node.js version from test matrix (because there are no longer guarantees that the platform is supported)
  • fixing a bug that changes how an existing feature has been working (because someone might be relying on the erroneous behavior without realizing it)
  • fixing a type definition (because it might break their CI/CD)
  • updating dependencies, when either of dependency updates is a major version (because of any of the above)

...and anything else that may break projects that depend on your package.

Many projects do not consider many of these breaking changes because of the stigma about often updating major version of the project. They will say things like "only a breaking change if", etc. to diminish the significance of the change.

Personally, I would rather use software that is v1000 that properly follows semver and has a proper CHANGELOG, than v1 software that has "stable API" and makes "soft breaking changes".

The easiest way to enforce proper semver is by using tools like semantic-release and force major version bump based on keyword detection in the commit log (like "breaking change").

Important exchanges from comments:

But if someone ask you "I see you have released version 2.0.0, what's new there?" And you tell them 2.0.0 contains changes to the spelling errors [in the API]...How ridiculous would that be?

That's literally what the major version is for:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API

That being said, you would typically not make this a breaking change by:

  • correct the API
  • create an alias using the erroneous API method and deprecate it

This way it would be a minor change, and major change would happen only once you drop the alias. Some libraries choose to keep them for years, until they batch them and do a single major version bump.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .