Semantic Versioning

Rant, Semantic Versioning Posted on

I'm honestly sick of the discrepancies that exist between versioning. As such, I'm proposing a universal versioning scheme with actual definitions that are easy to understand and follow.

One of the biggest complaints from non-technical users of alpha/beta/release candidate software is "it doesn't work." Well duh! The problem is that most users have absolutely no idea what beta even means; and this isn't their fault, its ours.

I remember when I was younger, Hotmail was cool. Anyone who had an email was legit. Hotmail was still in beta and Microsoft explained beta as "fully functional with more features to come!"

Originally, Alpha releases were meant to be "internal only." This meant that non-technical people within an organization would try the application. It wasn't released with bugs; this was purely to get feedback, mostly on things like UI, speed, and usage. However, that was back when people used Waterfall development.

Now with Agile Development methodologies, we involve the client in (almost) every decision. While my opinion on Agile Development is beyond the scope of this article, it has changed the way we think about semantic versioning and releases.

Some people argue that every push to git should be a version bump. You're a fucking idiot. I'm not bumping 0.0.1 because I changed a fucking CSS style. Quit trying to make your product look updated. Other people you should version bump every time you create a git tag. You're also a fucking idiot. A tag is like a checkpoint in a video game. A version bump is buying a new game, not a save-state. I digress. However, now we introduced the x.y.z notation that we commonly see in software releases. According to most sources, the breakdown of x.y.z is:

  • x - Major
  • y - Minor
  • z - Patch

This was great - Oh, except no one ever really bothered to define major, minor, and patch - Let's define them now:

  • major - Seriously changed the software such that it's drastically different from it's previous versions. If this was a paid product, a major version bump would cost money.
  • minor - Added a new feature that significantly improves the product. Alternatively, this could remove a potentially malicious and/or problematic feature.
  • patch - Bug fix.

Well that's nice. Now we have a solid understand of semantic versioning - up until about 5 years ago. Open source exploded (thanks github) around that time. Collaboration became easy, and software projects became highly distributed (thanks git). However, this has caused a huge problem for versioning. It's caused so much of a problem that we added another fucking dot to versioning!

Now, instead of x.y.z, we have x.y.z.α. But α, unlike x, y, and z, is not a number, it's a word or phrase or convoluted nothingness. Rails is my favorite example of this.

Do we really need another predicate for versioning? Wasn't 3 enough?

This has caused a LOT of confusion among non-technical people. They don't know what a release candidate is (rc), nor do they understand alpha, beta, gamma releases. This additional dot encourages developers to release software that isn't ready for production! Because if x == patch, then α == untested, poorly documented, possibly removed feature. AKA non-release.

We seriously need to ditch the additional version and stop releasing buggy software. If it's not ready, don't release it. Furthermore, we need to better define things like alpha, beta, and gamma releases. Here's my proposal (summarized):

  • alpha - Never sees the light of day. Don't publish it. Nothing. A piece of software should be tagged as alpha, but never released. This is the "we finished our wish list, now let's try and break it (as developers)." I prefer to call this the "edge-case" stage. It's only for developers. If this is a gem, it does not get published; it is shared via source or tarball. The developer or system administrators install the software.
  • beta - Exposed to a small (private) group of users. This may be other developers or users who are specialists in the field of the software. This is tagged as beta, but never released. I prefer to call this the "use-case" stage. It's only for experienced users (in terms of the speciality of the software). If this is a gem, it does not get published; it is shared via source or tarball. The developer or system administrators install the software.
  • gamma - Exposed to an entire organization. This does not apply to all kinds of software, especially open-source. This is tagged as gamma, but does not exist outside of the organization. I prefer to call this the "load-balance-case." As a developer, you are mass-testing the software for excessive workload, in a real production environment. If this is a gem, it does not get published; it is shared via source or tarball. The developer or system administrators install the software.
  • release candidate - Go public.

Now, when you go public, what version to you start with? Try 1.0.0. Move along now.

About Seth

Seth Vargo is an engineer at Google. Previously he worked at HashiCorp, Chef Software, CustomInk, and some Pittsburgh-based startups. He is the author of Learning Chef and is passionate about reducing inequality in technology. When he is not writing, working on open source, teaching, or speaking at conferences, Seth advises non-profits.