Proposal to adhere to Semantic Versioning 2.0.0 across packages

Community
#1

I’d like to propose that we adhere to the widely accepted “Semantic Versioning 2.0.0” (http://semver.org/) across all of our packages, with the caveat that we’ll only move a package to 1.0.0 after it is out of alpha or beta.

To recap, version numbers according to this standard look like this:

MAJOR.MINOR.PATCH
0.4.8

Adopting this means the following:

  • With every patch, we’d increment the patch number.
  • With every new feature that preserves backwards compatibility, we’d increment the minor number.
  • With every re-haul that breaks compatibility, we’d increment the major number. That said, initially it’s ok and even somewhat preferred to move quickly and break backwards compatibility and keep the “0” major number, as long as the library hasn’t been integrated into external libraries that we do not maintain. That’s because they may depend heavily on the semantic versioning system to determine whether a new version should be automatically upgraded to or whether explicit user authorization should be required (for example, NPM has a mechanism for this).

Would love your thoughts.

1 Like
#2

Does this mean external libraries shouldn’t be using our libraries until they’re out of alpha/beta?

#3

No they totally can and should.

Basically, if you are about to break an interface / break compatibility and you cannot ensure that you can upgrade all libraries in tandem that will be affected, then you should upgrade the major number (or you should make sure not to break compatibility).

#4

If we’re not incrementing the major number to 1 until after a package is out of alpha/beta, does that mean people using our alpha/beta libraries should be prepared for compatibility/interface breaks with any update?

#5

One thing I do is look for published libraries on NPM that are dependent on a library.

Blockstack Profiles JS has two libraries that depend on it: https://www.npmjs.com/package/blockstack-profiles. Thus, we’ll make sure not to break the interface without moving it to 1.0.0. This package has been around for a bit and is pretty stable. We might even be able to bump it up to 1.0.0.

In contrast, a package that just came out at 0.1.0 will likely change rapidly and will not have been announced yet. There will be no expectation that someone will be depending on it and we can check npm to make sure.

The way I see it is: after it’s been around for a bit of time, it’s more important to be careful. After the package has been announced, the upgrade methodology should be strictly adhered to.

1 Like