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
Although this is not the newest article, here are my two cents.
This depends; if the latter part is explicitly stated in your documentation you could change it and still only increment a minor version, cf. https://semver.org/#spec-item-1
Everything coming below this heading is just not possible when using SemVer (cf. https://semver.org/#spec-item-3), I know that wordpress.org proposes this, but they’re not using SemVer anyway.
If you change even the tiniest thing, you’ve changed your plugin so it MUST be a new version.