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.

Tags: semantic versioning, semver, software patches, version control
CSS goblin. Sass hacker. Margin psycho. Author of Sass Guidelines, SassDoc, Sass Compatibility, Browserhacks and a lot of Sass stuff.
  • 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

  • Arne K. Haaje

    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?

    • Hugo Giraudel

      You could use git hooks I suppose.

  • 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 ?

    • Hugo Giraudel

      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?

Ending Soon
Free SitePoint Premium

Get one free year of unlimited book and course downloads on SitePoint Premium!