• Skip to primary navigation
  • Skip to main content
Sal Ferrarello
  • About Sal Ferrarello
  • Speaking
  • Connect
    Mastodon GitHub Twitter (inactive)
You are here: Home / Programming / SemVer for WordPress Plugins

SemVer for WordPress Plugins

Last updated on November 30, 2015 by Sal Ferrarello

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
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.

Share this post:

Share on TwitterShare on FacebookShare on LinkedInShare on EmailShare on Reddit

Filed Under: Programming Tagged With: WordPress, WordPress Plugin

Reader Interactions

Comments

  1. Alex says

    February 16, 2018 at 7:50 am

    Although this is not the newest article, here are my two cents.

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

    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

    No Version Change

    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.

    Reply

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Copyright © 2023 · Bootstrap4 Genesis on Genesis Framework · WordPress · Log in