(Semantic) Versioning in WordPress Userland

Everyone seems to allude to Semantic Versioning (SemVer) when talking about software versioning, if you look closely though, even when vendors explicitly claim SemVer they frequently don’t stick to its principals. Although this is not at all limited to WordPress or even PHP, I will take a closer look at SemVer in WordPress in especially WordPress plugins.

WordPress Core Versioning

Recently someone claimed that WordPress core uses a "modified version of SemVer, particularly with regard to breaking changes", which is utter nonsense. WordPress core does not use SemVer at all – one of the highest goals of WordPress is to never break backward compatibility!

WordPress has a decimal-based version numbering system with added maintenance versions. So basically 4.9.4 is actually 49.4, and the next major release will be 50! Although the maintenance/patch number of WordPress version usually only includes bug fixes it does not indicate if new features have been added.

WordPress Userland – Themes, Plugins, etc.

"WordPress[.org] is not an opinionated platform" and therefore does not force you to use a versioning system. This allows a plugin developer to use whatever versioning system they want to use. A lot of developers automatically think "SemVer" whenever they see a version number in the format X.Y.Z. The core principal of SemVer, however, is not the format of the version number, but the semantics of the version number concerning the public API.

SemVer is about the semantics of the version number concerning the public API

The term public API is essential in this case: The first item of the SemVer spec states that your piece of software "MUST declare a public API … [that] should be precise and comprehensive". And only if you change this public API it is considered a breaking change. Now I don’t want to get into "What is a breaking change?", "What is the public API of [plugin-name-here]?" but the contract or pinky promise developers incur claiming to use SemVer.

Yoast

Yoast—undisputedly the most popular SEO plugin for WordPress, claims to use "Semantic versioning (with a slight twist)". The only twist I can see here is that it is absolutely misleading. On another project yoast states "We follow semantic versioning with an extra strict rule for MAJOR versions. We will do a major version bump whenever we add new methods."; well, no, they DO NOT follow semantic versioning. They have valid reasons not to use SemVer (especially in the whip project), but by claiming to do so, they violate the SemVer contract.

WooCommerce

Starting with version 3.0.0 released in April 2017 WooCommerce has adopted semantic versioning. The update to 3.3.0 has broken several sites using template overrides over hooks, and subsequently, the release has been pulled from wordpress.org. WooCommerce might just have a problem with their public API because even though they are encouraging hooks over overrides, both are documented and present.

These are just two examples; maybe I’ll expand the list as I come across more of these. I don’t advocate for using semantic versioning in WordPress if you ask me it does not matter. Unless WordPress core introduces any form of dependency management use whatever versioning system you like, version numbers are for machines not for people. Continue using RomVer—Romantic Versioning, that’s fine. But once you call it SemVer, you better use SemVer and not your un-semantic version of it.