Semantic Versioning 101

Trevor Ewen
Apr 15, 2019 · 5 min read

Semantic Versioning 2.0.0 (semver.org) is a robust and elementary standard that encapsulates a wealth of information about the software you’re publishing or consuming.

Open source veterans know and understand the importance of this standard. If you’ve run a project in long-term maintenance mode, you come to realize its power one way or another. Still, enthusiastic, fast-moving dev teams like to find ways around this standard. I’ve seen more than a few engineers decide to invent their own ideas around major, minor, and patch increments. Their rationale is rooted in aesthetics or their own release schedule.

Image for post
Image for post

A key principle

Aside from the concise and complete information at semver.org, it is critical to understand:

This illustrates the single, largest misuse of semantic versioning. Developers and product managers really want to wait for the big X.Y release, despite the fact that they have been introducing breaking changes now for months and incrementing patches.

Note: It’s a different thing to plan breaking changes around a release schedule. That is good project management. I am talking about teams that break functionality and increment a patch because the breaking change doesn’t “impact too many consumers” or “is not that consequential.”

To follow are some examples that illustrate some tricky versioning situations you will encounter.

Major versions

Bullet #1 in the summary from semver.org: MAJOR version when you make incompatible API changes.

Here are three examples of module changes. Only one of these is a major increment:

Image for post
Image for post
Major version examples

For the sake of argument, we’ll assume a top >> bottom no breaking changes introduced for this public method. This is a canonical definition of a minor version increment. I understand the pressure from the communication’s side. If you make huge, non-breaking changes, it sounds much better to advertise version 2.0.0 than 1.3.0. On behalf of your consumers, it’s much better to know there is a safe upgrade path. This is especially true for applications that are in maintenance mode.

This is a tiny change. In contrast to the last example, your gut instinct probably does not want to call attention to a tiny change with a major version increment. As a mental test, anything that could break the ongoing use cases for existing consumers should be a major version increment. Don’t fall into the trap of sneaking this one into a patch or minor version.

This is a typical example of a patch increment. New functionality created a regression on existing functionality. We’ll discuss patch versions at more length in the section below.

Minor Versions

Bullet #2 in the summary from semver.org: MINOR version when you add functionality in a backwards-compatible manner.

Image for post
Image for post
Minor version examples

New functionality, no breaking changes. I had envisioned this as a method or constructor that helps the consumer build a complex configuration. That configuration is then passed in an entirely backwards-compatible way. Assuming you have met that compatibility bar, this is a good minor version.

Renamed, changed, streamlined >> All words that foreshadow a possible major increment. This is obviously the case for public methods. There are exceptions when you have only refactored internal functionality. Configuration properties are public. This is not a backwards-compatible change. This is a major increment.

Semver.org says that “substantial new functionality or improvements within private code” can be the cause of a minor version increment. They leave decision making up to the developer. I would not be afraid to use minor version increments to signal performance improvements. I always want my consumers to feel a need to upgrade to the latest patch. They should want to upgrade to the latest minor version.

Patch Versions

Bullet #3 in the summary from semver.org: PATCH version when you make backwards-compatible bug fixes.

Image for post
Image for post
Patch version examples

This is not a regression. It is entirely possible that some consumers have worked this public behavior into their workflow (see xkcd). While it is a bug from the perspective of your project plan. This is a case for a major increment. I recommend bundling a change like this into a release along with other ‘necessary’ breaks of functionality.

This is a really nasty one. By the strict definition of the standard, this is a major release. Imagine, you could go from 2.0.0 >> 3.0.0 overnight because of some sloppy typing and review. Still, a project with proper tests in place should catch things like this. That’s a separate topic, but this example should serve as a warning.

Something was working as expected until now. Minor or major increment comes along, now French consumers are seeing Spanish. This is a good example of a patch. No consumer chooses this kind of errant behavior. It’s not new functionality (unless you never supported French to begin with). This is a good case for a patch.

Go out and version, in peace

This week, I was working on a throwaway script and needed a logger that could write JSON to a file. I grabbed the popular winston library via npm. The latest 3.2.1 library was automatically installed. I copied over an existing setup script for my logger from a project that was 2–3 years old.

The old project had been locked into the 2.x.x version. My logger construction broke. No mind, I downgraded my dependency to 2.x.x and kept working on my throwaway script.

I read no release notes. I did not go to Stack Overflow. I did not go poking through the code. The properly applied, semantic version told me everything I needed to know.

I added a task on my @Trello board to upgrade my logger in the future (and why not make it better, etc.). For now, I can get back to work, in peace.

HackerNoon.com

#BlackLivesMatter

By HackerNoon.com

how hackers start their afternoons. the real shit is on hackernoon.com. Take a look

By signing up, you will create a Medium account if you don’t already have one. Review our Privacy Policy for more information about our privacy practices.

Check your inbox
Medium sent you an email at to complete your subscription.

Trevor Ewen

Written by

Software developer & investor. Opinions are my own.

HackerNoon.com

Elijah McClain, George Floyd, Eric Garner, Breonna Taylor, Ahmaud Arbery, Michael Brown, Oscar Grant, Atatiana Jefferson, Tamir Rice, Bettie Jones, Botham Jean

Trevor Ewen

Written by

Software developer & investor. Opinions are my own.

HackerNoon.com

Elijah McClain, George Floyd, Eric Garner, Breonna Taylor, Ahmaud Arbery, Michael Brown, Oscar Grant, Atatiana Jefferson, Tamir Rice, Bettie Jones, Botham Jean

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store