Semantic Versioning – Open Source License Compliance & Security

Semantic Versioning is a specification for version numbers. It specially makes sense for software libraries and for everything what can be a dependency in a bigger system. A semantic version number always follows this pattern MAJOR.MINOR.PATCH.

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Patch Versions

Let’s say you are the maintainer of an open source library, an XML parser, with the version number “1.0.0”. And now you want to release a new version because you fixed some bugs. For the bug-fix you

changed some method implementations,
but you didn’t add new methods
and the changes are backwards compatible

In that case the new release is just a patch. That means you would update the patch version in your version string. That would be “1.0.1“.

Minor Versions

Now let’s say you want to add additional features to your software library. The current version “1.0.1” can read XML files from hard disk and now you want to add a new feature which allows to read XML files from the Internet. For this new feature you are adding new methods and you extend the public API of your library. That’s why you count up the minor version in your version number. So the next release looks like this “1.1.0″. And every time you count up the minor version you have to reset the patch version to 0.

Major Versions

During your work on this XML parser you learned a lot of new stuff and you decide to completely refactor the library to make it even more awesome! During the refactoring you change the public API on the library and the new version is not backwards compatible anymore. That’s why you release version “2.0.0″. It’s a major version! Every time you count up the major version number you have to reset the minor and patch version to 0.

People who rely on your XML parser can now immediately see that the new version will, very likely, lead to compilation errors and break their build. Seeing the version number they now know that they have to be careful with the update, they have to check the change logs and the migration path.

Advantages

Semantic versioning is awesome, because you can see immediately how big the changes are without digging into documentation and source code. Already on the version number you can see if you can

easily update that library (Patch) or
their are new features to check out (Minor) or
you have to be careful because the update will break your system (Major).

It makes the life of software developers so much easier!

Negative Example

Unfortunately not all open source libraries are using semantic versioning. Some of them are using very wired version numbers. For example this here:

20050307052300

That’s a timestamp version number, including year, month, day, hour and minute. Unfortunately that doesn’t tell me anything about the changes in that release. I don’t know if that is just a patch release or maybe a major release that will break my build! Or maybe it is a minor release with new features. But who knows? This kind of version numbers are totally bullshit!

Conclusion

Check out the full spec at semver.org. It takes less then 5 minutes and it will make you to a better software developer. I promise!

I just showed here an easy going example. Semantic versioning is more then just 3 numbers and 2 dots. It also supports pre releases and build numbers and the whole version string can be more complex. For the complete syntax check out the Backus–Naur Form Grammar for Valid SemVer Versions.

By the way, I’m working at VersionEye, a notification system for software libraries. If you want to know if a software library is using semantic versioning, just visit it’s page at VersionEye and you will see a green or red hint like here for Ruby on Rails.