SemVer for WordPress Plugins

I’m a big fan of Semantic Versioning, where each version is made up of three numbers:

• major version
• minor version
• patch (a.k.a. bug fix) version

I’ve found there are some nuances when maintaining a WordPress plugin and maintaining SemVer for it. Here are some notes to help.

Major Version Increment

Anytime the plugin makes breaking changes, the major version (the first number) should be incremented. The tricky thing here is with many WordPress plugins, breaking changes may not be obvious.

Here are some examples of breaking changes that are easy to miss.

• removing a hook name
• changing a hook name
• renaming a function or method that can be called publicly (even if it isn’t intended to be called from outside the plugin)

Minor Version Increment

When you add functionality in a backwards-compatible manner.

Patch Version Increment

Bug fixes are an obvious case for incrementing your patch version.

Adding a New Translation

When adding a new translation to a WordPress plugin (and making no other changes), you should increment the patch version.

As discussed in this thread on translations and SemVer, in some other systems (including WordPress core) adding a new translation does not require any change to the version number but when working with WordPress plugins incrementing the version is a best practice.

No Version Change

There are instances where you may push updates to the WordPress.org plugin repository but incrementing the version is not appropriate.

Tested Up To

When a new version of WordPress core is released, it is good form to test your plugin and update the plugin’s “Tested Up To” value. However, this change in the readme.txt file does not require incrementing your plugin version. Your plugin hasn’t changed, you’ve just updated some information about it.

When wordpress.org sends out emails reminding plugin authors to test on the latest version, they specifically ask that you do not increment your plugin version when updating your “Tested Up To” value.

For each plugin that is compatible, you don’t need to release a new version — just change the stable version’s readme value.

I’ve written a related post about how to Increase the “Tested up to” Value for a WordPress Plugin.

Other Meta Data in readme.txt

When updating other Meta Data in readme.txt, there is no need to increment the version number. Some examples where the plugin version number would not need to be incremented include:

• modifying the description
• adding or modifying a FAQ
• adding or revising screenshots
• adding or modifying a banner or icon image

Sal Ferrarello (@salcode)

Sal is a PHP developer with a focus on the WordPress platform. He is a conference speaker with a background including Piano Player, Radio DJ, Magician/Juggler, Beach Photographer, and High School Math Teacher. Sal can be found professionally at WebDevStudios, where he works as a senior backend engineer.