WordPress is releasing version 4.9.6 soon. This version number (which follows 4.9.5) is including a whole bunch of features meant to comply with the GDPR, the new European privacy law. This new feature set is a great idea, this version number is not. I say that because of semantic versioning.

Now, this isn’t meant to be an article about WordPress—I’d publish that on WPShout. But one of the biggest reasons I care so much about semantic versioning is that WordPress demonstrably does not. And while it’s not the end of the world — WordPress is still huge, despite ignoring semantic versioning — I think WordPress would be better if it did. So would your project.

What are Semantic Version Numbers?

The way that software version numbers should work is called semantic versioning. Semantic versioning is my preferred way of tagging software releases. Why? It’s the most well-known way to track how the software you interact with has changed. It makes it relatively easy to assess (intended) compatibility.

Here’s the simplest possible summary of semantic versioning, from what is widely regarded as the canonical source:

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes.

Semantic Versioning Examples

By “incompatible API changes” on a MAJOR version change, I know I can’t upgrade with any guarantee of safety. That means that I understand that from 4.2.3 to 5.0.1, things that used to work may not. In the WordPress world, that would mean that my plugin or theme that relies on yours may break. In the web framework world, that’d mean that my code which inter-operates with your library or framework may need to be edited. Semantic versioning prescribes that this only happen on major releases, when the very front number changes.

When I hear that MINOR version will be backwards-compatible, I know I can update safely. I know that if something broke in our code interacting, it’s because you missed a test. Not because you intended this. So that lets me know that any incompatibility is something you regard as a bug. There may be new features in this release I’m interested in. I may choose to look into those.

When I hear that PATCH numbers are merely bug fixes, I know I should upgrade to them quickly, and with knowledge that nothing will have outwardly changed in your intent.

Taken together, this is a lot of power from a few numbers. If you’re using semantic versions, and I’m using version 1.7.4 of your software, I know that I can safely go all the way to a version like 1.12.68 without issue. I should also know that if it exists, I may have problems and complications if I try to update to 2.1.5. Further, I should expect that 1.7.5 would only fix minor bugs for me, while 1.8.0 will still be compatible. But you’ll have added a few features that I should check out to make my working with that changed software better.

Holistically, this system of semantic versioning has embedding into a few short characters, a great deal of meaning about intent. Software version numbers are something that we’ve agreed can be really useful shorthand for us to communicate with each other. They’re very brief and terse communication, like semaphore flags. A few can say a lot.

Other Methods of Software Versioning

There are a number of other ways that you can number software, and none of them are wrong. After all, if you’re making your code freely available, I don’t have a ton of room to complain. But I do find most other schemes I’ve encountered less useful than semantic versioning.

A truly sadistic scheme might tag every release with a random number generator. So the bug fix release after 3.21.7 was 67.4.92. 67.4.92 is then followed by a bunch of new features in 5.8.1. I’ve (thankfully) never seen a strategy that chaotic. But such a strategy wouldn’t always stop me from using your software. It would be something I’d have to factor into my decision, but if your stuff’s really great it may not be such a big obstacle that I wouldn’t use it.

The Wikipedia page on the topic covers a number of systems that are used to number software in great depth. The one used by TeX, a well-known and well-loved typesetting engine, caught my eye:

Since version 3, updates have been indicated by adding an extra digit at the end, so that the version number asymptotically approaches π [pi]; this is a form of unary numbering – the version number is the number of digits. The current version is 3.1415926. This is a reflection of the fact that TeX is now very stable, and only minor updates are anticipated.

The page also brings up somewhat more familiar strategies like decimal numbering — 1.168 — or date based systems. Windows famously, though hardly exclusively, went to named releases for a long period before returning to numeric ones with Windows 7, 8 and 10.

Why Versioning Is Communication

Version numbers are a complicated topic that I’ve now solved by explaining semantic versioning. So confusion about compatibility will never cause complications or strife anywhere in the world ever again. You’re welcome. 😜

More seriously, if you’re in the business of releasing software, I heartily encourage you to use semantic versioning. There are reasons—popular ones include marketing, art, personal eccentricity, or some idea you think is better—it may not be the right approach for your project. But it’s the sanest and best place I can think to start.

And the reason for that is that it saves you from needing to (for example) explain in long written blobs of text what people should expect in the next release of your consumer software or code library. Because the most common answer to software versioning is “use semantic versioning” a great deal of hassle can be avoided by adopting it.

Why WordPress’s Un-semantics Frustrate

Thanks to semantic versioning’s popularity, anytime we see a software version numbers in a digit.digit.digit format, we expect meaning in those numbers similar to, if not identical to, the standard.

Similar to, but not identical with, the semantic versioning standard is what you get in WordPress. WordPress effectively just does “major” and “patch” releases. And generally assures compatibility between major releases. So in some way, we can assume that version 4.4 is backwards-compatible with 4.3. This would typically make them “minor” versions, but (intended) compatibility hasn’t been perfect or universal historically. Specific examples are escaping my mind, but version 4.4 of WordPress probably broke some (small fraction of) 4.0 compatibility, as did 4.8 (probably).

Given that relatively solid track record of only-minor releases, why in May of 2018, is WordPress releasing a 4.9.6 with a bunch of new features? Because for marketing reasons BDFL Matt Mullenweg is holding WordPress 5.0 to be the release where the new visual editor “Gutenberg” is added. This means that if the WordPress team want to release something before 5.0, they must release a 4.x. And because in WordPress, people have never seen version numbers like 4.10.0 (3.9 gave way to 4.0, so 4.9 must give way to 5.0), we’re stuck with a major set of new features coming out in 4.9.6. No reading of the semantic versioning standard ever prescribed that.

This is really annoying for people who want to rely on finding useful meaning in version numbers. The only way you would know to expect that new features will go in in 4.9.6 is if you’re following the community news and discussion. Few people do.

It’s great that WordPress is getting GDPR-compliance-based changes. It’s also great that Gutenberg’s reservation of “5.0” isn’t stopping all forward-progress on the rest of WordPress. But it’s bad that 4.9.6 isn’t as safe and simple a release as 4.9.1 or 4.9.5. No one will know that from version number alone either.

Why You Should Be Thoughtful About What You Communicate

At heart, I think semantic versioning matters because we’re all just monkey doing our best to understand each other.

We’re helped in this quest by language. Number are a part of that language. Being careless about your software version numbers because you can use words to explain is silly.

Language helps us describe indescribable feelings more succinctly. It’s a remarkable feat, but they’re slow and plodding. Numbers help us quickly grasp the difference between “a lot” and “really quite a lot” better. Version numbers help us understand “I meant that to break” from “I hope all your stuff still works” very quickly. Semantic versioning is a powerful and compact encoding of intent.

We must be thoughtful about what we communicate in software because understanding what a software tool does is hard. Being thoughtful and clear about using well-known methods of communication makes it easier. A little. 🙃 And that little bit of speed in understanding our project is worth that little bit of extra effort it costs us, as software authors.

Because we are thoughtful (caring) people, we use communication tools like semantic versioning. Happy hacking!