Semantic Versioning: Why You Should Be Using it

By Hugo Giraudel
We teamed up with SiteGround
To bring you the latest from the web and tried-and-true hosting, recommended for designers and developers. SitePoint Readers Get Up To 65% OFF Now

Semantic Versioning (referred to, for short, as SemVer), is a versioning system that has been on the rise over the last few years. With new plugins, addons, extensions, and libraries being built every day, having a universal way of versioning software development projects is a good thing to help us keep track of what’s going on.

What is SemVer?

SemVer is a 3-component system in the format of x.y.z where:

  • x stands for a major version
  • y stands for a minor version
  • z stands for a patch

So you have: Major.Minor.Patch.

How Does SemVer work?

SemVer relies on bumping the correct component up at the right time. Therefore, determining which type of version you should be releasing is simple.

If you are mostly fixing bugs, then this would be categorized as a patch, in which case you should bump z.

If you are implementing new features in a backward-compatible way, then you will bump y because this is what’s called a minor version.

On the other hand, if you implement new stuff that is likely to break the existing API, you need to bump x because it is a major version.

Why SemVer?

Because it makes sense. If there is one thing I’ve learned, it’s that versioning without guidelines basically means nothing. Moving to 4.2? Okay, fine. Why? Why not 5? Why not 4.1.1? Why not 4.11? Why not 4.1.oh-snap-new-version?

Following strict guidelines helps give meaning to version numbers.

For example, if you see version 1.3.37, then you’ll know this is the first major release, but there have already been 3 minor versions bringing new features. However, you’ll also note that this is the 37th patch in this minor version, which means there were a lot of bugs (little or big) involved.

Also it helps a lot in managing dependencies. Let’s say you are building a library called Unicorn. For whatever reasons, you have Rainbow as a dependency. When you get your lib out of the box for the first time, Rainbow is versioned 6.6.6 (looks nifty, huh?).

That means you can specify Rainbow as a Unicorn dependency as greater than or equal to 6.6.0, but less than 7.0.0. Remember how the first number is the major patch with backward-apocalyptic changes? If someday Rainbow moves up to 7.0.0, nothing tells you that it won’t break Unicorn, so it’s best to keep it at version 6.

Things to Keep in Mind

Now that you know what SemVer is, let’s look at some of the things that might trip people up when first starting to use it.

It Starts at 0.1.0

One thing to note when using SemVer is that it starts at 0.1.0 and not at 0.0.1 like one would assume. If you think this through, it makes sense. You do not start with a patch, you start with a set of features as a first draft for your project, hence version 0.1.0.

Before 1.0.0 is Only the Development Phase

Whenever you are building a new piece of software, there is always a phase where you keep asking yourself: When should I release the first official major version?

Here are a few hints to help you answer to this question: If your software is already being used in production or has users depending on it, then you should already be at 1.0.0. Also, if you are worrying a lot about breaking the current API, this likewise probably means you should be running 1.0.0 already.

Otherwise, keep in mind that versions below 1.0.0 are basically the development rush, where you focus on getting stuff done. Prior to 1.0.0, you shouldn’t be afraid of breaking things, and you’ll do whatever needs to be done so that when 1.0.0 is reached, it’s stable.

About Pre-releases

Before deploying a major version, you usually go through a lot of work that need to be tested again and again to make sure everything’s okay. That’s typically the moment you’d like to have a pre-release.

With SemVer, pre-releases can be defined by appending a hyphen and an identifier to a version. For example, a pre-release for version 1.0.0 could be 1.0.0-alpha.1. Then if another build is needed, it would become 1.0.0-alpha.2, and so on.

Final Thoughts

If you are not using SemVer, there is no legitimate excuse not to use it on your next project (or current project?). Not only does it help to keep things clean and meaningful, but it will also help other people who might be using your project as a dependency.

We teamed up with SiteGround
To bring you the latest from the web and tried-and-true hosting, recommended for designers and developers. SitePoint Readers Get Up To 65% OFF Now
  • David Maxwell

    I’m confused – how is this different than the “standard” versioning system that most developers have been using for years?

    • LouisLazaris

      Probably many have been using this system, but I don’t think many of them have been following these rules strictly. I think that’s the point, that you should increment various parts of the version number under specific circumstances, based on certain qualifications, rather than just arbitrarily changing it when you make an improvement to your product.

      • Jeff Jones

        this is just going to confuse alot of people

        • Marko Siladin

          What is the “standard” versioning system? At least if you say that you are using “Semantic Versioning” people know what rules you are following.

          • Jeff Jones

            every time you do a release, you bump the version up – semver only makes sense to codebases which expose a public api (ie – an npm module), otherwise “semver” will clearly just discourage fast iteration

  • Are there any tools (on Linux) or techniques to integrate with git, so that when your master branch merge in some other branch, your version is bumped?

  • Ravi Kumar

    Is there any range for x.y.z
    like as suppose 0.1.9 becomes 0.2.0 range (0-9) after tenth patch ?

    • Actually I thought about talking about it in the article, then thought it was clear enough. I should never assume this kind of things, hehe!

      When you reach 0.1.9 for instance, next version can definitely be 0.1.10. There is no limit. If next version is patch, it should be 0.1.10. If next version is a minor version, it should be 0.2.0. If next version is major version, it should be 1.0.0.

      Hope it’s clear.

  • Leonid Makarov

    What would be the rules for pre-release versions to move from alphas to betas to rcs to to the actual release?

  • “If you implement new stuff that is likely to break the existing API, you need to bump x because it is a major version.”
    So if I do the above but not likely to break the existing API, is it a major upgrade or minor upgrade ? Because I want to create a new feature but all prior features are still existed and working well.

    • Would be minor. :)

      • Thanks. But I think my current project will almost never have a major upgrade because I aim my project to be consistent. So, there will be less or almost no deprecated features. So, how does this affect by semantic versioning ? Will it stuck only at 1.x.x ?

        NB : My project doesn’t really have “API”s because my project is only related to HTML & CSS. No JS.

        • Yep.

          • Thanks. I want to ask a question again.

            If my current project version is 1.x.x and I make some deprecated features and new features there then there will be a major version increased. But I don’t want to make a real upgrading instead I separate 1.x.x with 2.x.x. It means that whether I have 2.x.x version on my project, the 1.x.x is still needed to be developed with minor upgrade without affected by the changes that make my project major version increased.

            So can I do that way ?


          • So basically you still support 1.x.x with bug fixes.

          • Not only I support 1.x.x with bug fixes but some minor upgrades. So, my users can choose which one they want to use, 1.x.x or 2.x.x. Is it okay I do like that ?

          • That is rather unusual.

          • The example is AngularJS. Angular 1.x is still being developed until now whether Angular 2 has been un-officially released.

          • If I’m not mistaken, Angular 2 is in development. Angular 1 is still the latest version.

          • Saw Giek Zhen

            Another example would be Jquery. It releases Jquery 2, but Jquery 1 is still on going and maintained concurrently.

          • Maintained. Not actively developed.

          • Hello, how about if I change the code inside but I don’t change the functionality ? I mean all the functions remain the same. The different is longer code become shorter code. Is this included into bug fixes or minor ? Thanks.

          • Probably bug fix. It’s irrelevant for the user.

  • Jake Wilson

    Any thoughts on using double-digits for minor versions? Is this okay to do? v1.56.0 ? Is there any real limit as to the number of digits for any of the numbers?

    • Nope. It’s perfectly fine. 1.0.0 doesn’t not necessarily come after 0.9.9. If you have 42 bug fixes on a version, or 42 minor updates, you go .42.

      • Daniel Tonon

        You should probably update the article to explicitly state this. There have been a few people ask this question in the comments now.

  • Luke Harrrison

    Seems simple enough :) Though in the context of something like a simple SASS framework for instance, what would you qualify as an API breaking bug, and thus requiring a new major version?

    • A function or a mixin not working the same as before.
      A variable, a function or a mixin not existing any longer.

  • Fouad Kajj

    Awesome !! Thanks :)