4.4.3. Formal

The previous informal method of versioning is something that can be used for linear evolution of your product. But it is not something that you could use for a more mature software. For such cases, you need to follow versioning scheme like Major . Minor . Patch.

This is how a typical approach would look like:

  • When you start working on something, call it version v0.1.0.

  • If you make just cosmetic changes, but don’t add a new feature, make it v0.1.1. i.e. Increment the last digit, patch version.

  • If you add a new feature, make the version v0.2.0. i.e. Reset the last digit to zero. and increment the second last digit, minor version.

  • And so on. You will have v0.2.1, v0.2.2, …, v0.3.0 and so on.

4.4.3.1. Major version: Zero and Non-Zero

The major part of the version plays an important role to announce compatibility. When the major version is 0, it means you are still developing you code. And something that was working earlier, may no longer work. An existing feature may still work, but the way that feature was exercised by end user may have undergone a change.

4.4.3.2. Compatibility

Let’s understand what exactly is compatibility. See for example Python 2 vs Python 3. If you have written a very basic hello world program written in Python 2, it may not work in Python 3 at all.

Python 2:

print "Hello World"

Python 3 and Python 2:

print("Hello World")

The older syntax of Python 2 is no longer compatible with Python 3. Therefor we say they are not compatible.

In the above case, you will know about the failure almost immediately when you run the code, because the syntax of the programming language is different. But some changes are not that straight forward.

Python 2:

>>> print(7/2)

3

Python 3:

>>> print(7/2)

3.5

See, the behaviour of / itself has changed here. One version returns a rounded number, other returns a floating point number.

These were the two very basic changes in Compatibility. In 1st case, API or function signature itself changed. In other case, the change was made in behaviour itself.

On one hand, such API In-Compatibilities are crucial to communicate up front. A change in Major version is an indication that something major has changed. Thus, it is a hint that they must look at the documentation to understand what has changed. This enables them to see if they are impacted or not, and they can have a conscious decision towards upgrade.

4.4.3.3. Making major version 1

For your first iteration you would have used version 0. The major version 0 means you are still experimenting. You are still seeking feedback of people around you. Neither you, nor people working with you are ready to put things into production yet. It is good enough for someone to look at it and play with it, but not yet fully ready to move into production.

But, once you feel confident that you can put things to a wider audience, you do not foresee any reason to change compatibility, make your version 1.0.0. This means you are more or less production ready, and you do not see any reason why your APIs should undergo some in-compatible changes. You may add new features and add new APIs, but what ever exists, does not change.

4.4.3.4. Making incompatible changes

As much as possible, you should try to avoid this. If possible, add new APIs, but still keep existing functionality intact. But if for some reason you have to take a call that things are not going to be compatible, increment major version and reset all other versions to zero.

So, in summary:

  • MAJOR version is incremented when you make incompatible changes.

  • MINOR version is incremented when you add new functionality in a backwards compatible manner.

  • PATCH version is incremented when you make minor iterations or bug fixes.

4.4.3.5. Further Reading

For further reading, see Semantic Versioning