Maybe I’m more observant than I used to be, or maybe there is a trend that’s actually happening, but one thing that I’ve noticed is that more and more WordPress developers are beginning to take interest in semantic versioning.

In short (and straight from the website), semantic versioning works like this:

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.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Easy enough to remember, right?

One of the things that sticks out, however, is that certain parts are meant to be updated and changed when there are “incompatible API changes”, when there are backwards-compatibility changes, and when there re bug fixes (and, in which I include, hot fixes).

This clearly makes sense in the context of a larger application such as, you know, WordPress itself, but Themes?

Let’s be honest: most WordPress Theme Updates don’t necessary fall under these same changes because they don’t have an API. Even more so, it raises the question of what would be considered a backwards-compatible change?

Or do they?

The more I’ve given this some thought, the more I think semantic versioning works just fine for WordPress theme updates, and it’s something that I’d love to see continued to be implemented.

WordPress Theme Updates

As it stands today, whenever a new version of a theme is released, many people often expect some set of new features, perhaps a new component to the design, or something that’s tangible – something they can see and/or experience.

But WordPress theme updates aren’t always going to include those kinds of changes, as anyone in software can attest to that. And that’s a good thing – updates should not always be about the look and feel of a theme, but about the architecture thereof such that it’s being continually improved.

But that’s probably content for an entirely different post.

Instead, how does semantic versioning apply to WordPress theme updates, especially when there’s no, say, API with which we’re working?

Major Versions

So if you look at the semantic version definition of what constitutes a major change, you see:

MAJOR version when you make incompatible API changes

But as we’ve already mentioned, WordPress themes don’t have an API.

Well, perhaps not in the traditional sense, but because of the concept of child themes, I think that themes can be considered to be an API and here’s why:

Any piece of software that can be extended or communicated with by its available functions has some type of API.

And because WordPress themes natively support (well, should support) the notion of child themes, then there are changes that can be made that could negatively affect child themes.

To that end, if we’re following semantic versioning, then the major version should only be incremented if a function is removed or a function name is changed.

Minor Versions

As for minor changes:

MINOR version when you add functionality in a backwards-compatible manner

We see this is nearly every single WordPress release (which is one reason some people hate on the codebase so much, but I digress on that topic).

Case in point: we see new APIs introduced while existing APIs remain and thus that’s why we jump from 3.4 to 3.5 to 3.6 and so on. New APIs are introduced, others persist so not to break the existing economy of themes, plugins, and whatever else people are building on WordPress. 

Finally, the Codex is updated to mark what APIs are now deprecated and what can be used in their place. This means the APIs that are deprecated will eventually be removed thus resulting in a major version update.

But what does this look like in the context of themes? I think it’s made up of two things:

  1. You introduce a new set of functionality or a new set of functions that either the users can experience.
  2. You introduce a new set of functions that developers can use that will not break existing child themes, but that will enhance their development efforts.


Lastly, these are defined as:

PATCH version when you make backwards-compatible bug fixes.

And I think this is something with which we’re all familiar.

Either changes are introduced that resolve bugs from the last major or minor release, or they are a sort of hot fix to resolve something that was going wrong when the theme was talking to, say, a third party service.

When working on themes, It should be really easy to identify with you should be incrementing the patch version: Simply put, you have the current version of your theme, a previous version of your theme, and you introduce a change that ensures both versions benefit – hence the backwards-compatibility – and ensures that whatever bug existed no longer does.

Semantic Versioning and WordPress

Semantic version has been something that’s been of interest to me ever since I’ve been maintaining plugins and working on themes. The truth us, I’ve not really been good about this, but it’s one area that I’ve aimed to strengthen over the year and moving forward.

As I’m getting ready to begin work on two new projects – one theme, and one application – I’ve been giving this more thought and trying to observe how many projects in the WordPress economy are actually doing this.

Perhaps I’ve failed to be as observant as I should over the past couple of years, but it looks like we’ve not always gone a good job with this; however, I’m seeing more and more projects beginning to adopt semantic versioning and I really like that.

Despite the expected outliers, hopefully this is something that’ll continue to spread.