Search code examples
semantic-versioning

How to introduce incompatible changes while remaining in major version zero?


I have a large personal software library that I have been working on and is currently working on. Currently, its version is 0.1.0.

It is not mature enough to have a major version of 1. I keep modifying the code and introducing incompatible changes that would merit an increase of the major version number. At the same time, some of my other libraries depend on this library and refer to it by the version number.

If I introduce incompatible changes and don't want to increase the major version from 0 to 1, how should I increment my version number?

The SemVer website is not very clear on that, it just says:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

Does "anything may change at any time mean" that an exception is made for a major version of 0 and that I can change the y and z numbers however I like?

For instance, if my version is 0.1.0 and I introduce an incompatible change, could the new version with that change be 0.2.0?

What others say

On this site it says:

In fact, the SemVer spec defines that anything starting with “0.” doesn’t have to apply any of the SemVer rules.

Another site also seems to suggest that it is OK to increase the minor version when the major version is 0 and incompatible changes are added:

So you just continue through the 0.x.y range, incrementing y for every backwards-compatible change, and x for every incompatible change.


Solution

  • It's up to you because

    • If other libraries depend on your software it means that your software has some consumed public APIs and if it has them... Why isn't already at 1.x.x version?
      After all... why is so important that your software reaches the 1.0.0 version only once it's stable? It could start with 3.0.0 or 4.0.0 once it reaches a stable version...
    • Your software isn't mentally decoupled from your bigger project because, in fact, you'll consider it "mature" only when the whole software (made of a lot of smaller libraries) reaches a "mature" version. But from a technical perspective it's already decoupled 😉
    • It's right that starting from 0 you don't have to strictly adhere with the semver rules

    Everything revolves around what is considered "mature". You told that your software isn't mature but what does it mean? That could be improved? That it doesn't cover all the corner cases? That it's not 100% tested?

    In the end: if you don't consider it mature continue with the 0.x.y versioning and increase the minor version but your immature software is already consumed by other libraries so it should now reach the 2.0.0 version 😉