Semantic Versioning

Semantic Versioning with Addison Berry The term "semantic versioning," or SemVer, is a way of numbering a software release. And it's something that's being adopted more and more widely by different software projects. So in this tutorial, we're just going to walk through a few basic steps. We're going to explain exactly what semantic versioning, how that works. We'll talk about some of the benefits and why people are switching over to semantic versioning. And we'll wrap up by showing how you can get more information and the actual specifications for it. So semantic versioning, as I said earlier, SemVer is a short form of it that you may see out there. So if someone was talking about SemVer, that's what they're talking about, semantic versioning. And it uses a three-number system instead of a two-number system for a release number on a piece of software. So you might be familiar with software release numbers that do something like 1.0, 1.1, 1.2. And with semantic versioning, we use three. And we're going to take a look at that in a second to see what that means and what it looks like. One of the important things about semantic versioning as well is that it requires a public API. So if you are saying you're using semantic versioning, you have to have some kind of publicly declared API because the semantic versioning numbering system is dependent on whether; things like whether or not you're breaking your API or how the version is changing the API. So if you don't have something that's sort of publicly declared that can be sort of looked at and measured against so you can actually see is this actually changing and breaking something or not, then the semantic versioning numbering doesn't tend to make, well, as much sense. So it's an assumption that you have a public API that people are tracking and able to use and interact with. And then with semantic versioning, you're letting them know what changes have been made to the software that affects the API. And then they can make a decision on whether or not they want to upgrade, or if they have to upgrade, what other changes they're going to have to make in their dependencies. So let's take a look at the actual numbers themselves. So here's just a made up version number. And you can see that we have three numbers. So the first number is the major version number. The second is minor version. And then the third number is a patch number basically meant for bug patching. So let's walk through each of the numbers individually. So a major version, whenever you increment the major version number, you are actually breaking the API. There's no backwards compatibility with the old API. So something-- like in this instance, this is version 8 of this software. This is not backwards compatible with the version 7 of the software. For a minor version, this does not break backwards compatibility with the version number before it. So 8.2 is backwards compatible with 8.1. We didn't actually break anything major here. This number is used for things that are like new features or big changes that are being made in the software, but it's not breaking backwards compatibility. The last number, this third number, is the patch number, which is meant for bug fixes. So every time we have a version of the software, every time we do security updates or fix bugs or those kinds of things, that just gets a patch number. And that should never break backwards compatibility. If you need to break backwards compatibility to fix those bugs, then you're going to end up having to increment to a whole new major version number. So that is the basic numbering system. That's why there are three numbers. They each indicate different kinds of changes. So by looking at the number, you can immediately tell sort of what the state of the piece of software is. So in this instance, we're on the eighth major version. So there have been seven changes that have broken backwards compatibility in the past. We're on the second minor version, which means there have been two feature changes and additions have been made. And we're on the sixth bug fix or patch, so there have been six bug fixes to the second minor version here. So after we did our second big feature push, we've had six bugs that we've fixed in the meantime. So if we had another bug that came along from 8.2.6, we would increment our release 8.2.7 for that bug fix. But everything else is essentially the same. Now, if we actually come along and we do a new feature, like we're really changing stuff and adding some new stuff to the site, we're going to increment the minor version up to 3 and that's going to reset the patch to 0, because there are no actual bug fixes for version 3 yet. So 8.3.0. If we get to actually breaking the backwards compatibility with the API, then we're going to increment the major version number up to 9. And we're going to zero out all of the rest of the numbers because we don't have any features or bug fixes in version 9 yet when we first release it. And we would begin all over. Again our first feature would be 9.1.0, and then our first bug fix to that would be 9.1.1. So that's the basics of the numbers and what those numbers signify. And it's very clear and distinct what each number is representing. So when you look at the number, you should have a very good sense of what the status of that code is, particularly in comparison to previous versions. Now, before you actually get to releasing something and you're working on it, of course you also want to keep track of your versions before you're talking about API changes and features and those kinds of things. So with initial development with semantic versioning, you're going to use the major version number of 0. So my first feature as I begin to work on my code is going to be 0.1.0. That's the first feature. And as I add features, I will increment the minor number. And of course, bug fixes will get the patch number. You can also use pre-release strings with semantic versioning. So things like alphas and betas and release candidates. You can also put in numbers with those. And you would just append that to the end of the release. So your pre-release, before you actually release a real version, would be 1.0.0 because that's where your public release-- like I've been doing all of my development, I'm ready to go. I'm going to put it out there for the public to begin using. That's 1.0.0. So if I was doing my alpha and then beta and release candidate for that particular release, I would just put that at the end, as you can see here in the slide. So development, you're going to start with 0. When you first make your software publicly available for other people to use, you start off with a major version of 1. And then you'll increment the three different numbers as we just discussed in the previous slides. So why go through this? Why have three numbers and all of this like very specific definition of what's going on? One of the main motivations for doing this was just to make really clear when you have compatibility or dependency problems. If someone is using your software, and especially if they're using an API and they're using it in a code way and they've written other code that's dependent on it in some way, when those things change it affects everybody else's work that they've done. And so it makes it very clear from the version number what is going on in terms of my code is compatible with or dependent upon 8.2.x. Or 8.x.x. People can decide what they need to do. But if you break that API, then people will immediately know that their compatibility and dependencies are probably broken and then they're going to need to update their stuff. So just to make it very clear which version people are using and what that actually means, what the implications are for other code that may be dependent on it. It also really encourages well-defined APIs. In order for you to know whether you're breaking an API or if you are still fully backwards compatible, you need to have a pretty clear idea of what your API is doing and how people are using it. And so it really helps to clearly define that and then when you make changes to think about in terms of that backwards compatibility in very clear terms. And that just is better for everybody in terms of documenting things and making sure that people who are using the software aren't caught by surprises. It can also help with upgrade decisions. If I'm just an end user of some software and I see that a bug fix has come out, chances are that's a good thing for me to upgrade to get that bug fixed. But I also know it's not going to majorly change anything in terms of how I'm used to using the software. If I see that the minor version has changed, then this is a new feature. There's some new change that's going on. But it's not going to break how the software works, so how I'm used to it working in terms of backwards compatibility. And then if a major version comes along, I know that things are going to be likely very, very different. And it can change how I make my decision about whether or not I should upgrade my software or not. It's just a clearer message to people who are using the software. So all around, it's just making things clearer and more explicit, which is, of course, just going to be beneficial to everybody, including developers of software so that you have a clear idea of what it is you're creating and communicating that well to the people who are using it. If you want to find out more details and get the actual specification for this, you can go to semver.org. And that is where you actually will find the explicit list That's where it says things like, you have to have a public API, how the numbering system works. It also talks about some edge cases and other things that I might not have covered in this short presentation. And it gets versioned just like semantic versioning, so you can always tell if there's been a major change in the specification by the number of the semantic versioning website. So in this short tutorial, we've covered what semantic versioning is and how we actually use it with the three-number system, why this is a good thing, and go check out more information at semver.org.