Advent Calendar #2 - Semantic Versioning explained

Since the beginning of software development, versioning has been a serious issue. With semantic versioning, a standard arose. In this post, I will teach you how it works and why it's great.

It works like this: You have a version number, that consists of three separate numbers. The first number signifies the so-called MAJOR version. It is increased by one if the public API breaks (so-called BREAKING CHANGE). This might be, because a public function changes its signature or a method is removed entirely, or class names change. Really everything that makes the dependent need to change its client code.

The second number indicates the so-called MINOR version, which is increased by one, if the public API gets new features that MIGHT be implemented. There is no need for action when upgrading to a new MINOR version. But it's like a present that might give you great new features, that you've been waiting for.

The third number indicates the so-called PATCH version. It is increased by one, with every bug fix, that resolves an issue within the code.

NPM knows this too

This standard is great because package managers like npm know them too. You can see the outcome of it, by running npm install. If a new minor version is published, npm install will not ask you, if you really want to install this. It just installs the latest patch version, because SEMVER indicates that this version is only better than the last one and does not require the client to change anything.

Practical examples

I have a library with the method getAll(filterObject: {query?: string}). I extend the filterObject with a new filter option. The type becomes {query?: string, createdAfter?: string}.

This will be a MINOR (0.X.0) update.

I fixed the hash function to hash a password.

This will be a PATCH update. Because I fixed a bug and the client does not have to deal with further API changes.

I rename the getAll(filterObject: {query?: string, createdAfter?: string}) method to query.

This will be an MAJOR upgrade. Because the client has to deal with this new definition

My top question: when to release a new version?

No, you do not have to create a new version after every commit. This is a common misunderstanding and haunted me for a long time.

You can release it whenever you want and you don't have to increment the MINOR version number by 10, if you group all the features in one.

In reality, it's often useful to group certain changes, especially breaking changes. Because they will make your clients have a bad time and you don't want that.

Conclusion

Versioning might look intimidating at first, but it's worth to learn. And let's be honest. It's not that complicated.