If you have a plugin in the WordPress repository, the plugin team requires that you have a version number.

However, I see a lot of plugins declaring arbitrary version numbers for their releases.

As an example, Jetpack, one of Automattic’s commercial plugins is currently on version 12.3 with the version 12.4 approaching.

• What does the first number mean?
• Have there been 12 versions with incompatible changes since the plugin was created?
• When there are versions released with only bug fixes, there is a number added to the version (12.3.1)

While this is somewhat helpful, it doesn’t follow a typical naming convention (1.2.1).

It’s plugin versioning like this that sets an expectation versioning can be whatever you want it to be.

Plugins should adhere to a consistent versioning methodology

Users should know what is being released in a new version of a plugin. The best version naming system I’ve found is Semantic Versioning (SemVer).

MAJOR.MINOR.PATCH

1. Update the MAJOR version when you make incompatible core changes
2. Update the MINOR version when you add functionality in a backward compatible manner
3. Update the PATCH version when you only make backward compatible bug fixes

Adhering to a consistent versioning system helps communicate what kind of software changes your update includes.

According to the specification, “version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next.”

The MAJOR version (1.0.0)

The Major version number determines whether you have introduced a feature or a bug fix that breaks backwards compatibility for users.

For example, this would include changing the plugin’s architecture and removing features actively being used by sites.

It could also mean removing or renaming an existing filter or action (Users might be using it to add some customizations) and updating the plugin would break custom functionality.

Creating that kind of change would need a signifier that if users want to keep some functionality, they shouldn’t update to the next release.

Any time you break backwards compatibility you should increment the MAJOR version.

Using SemVer, you can communicate the change with your users so they can make an informed decision to update.

The MINOR version (1.2.0)

Update your minor version any time you add new functionality.

You can also include bug fixes here, but the key is that each new minor version should add some kind of new functionality.

When this version number is updated, users should expect to update without major issues because it’s an addition of features (and bug fixes). No breaking changes.

The PATCH version (1.2.1)

Finally, you’ll want to bump up the patch version any time you create a new release that ONLY contains bug fixes.

Often this number is tied to a hotfix or related to security issues that need to be pushed out to users quickly.

Keep in mind, if you push out a hotfix and notice an issue with the release, do not update it directly—users won’t get the updated codebase.

Create a new release and version it appropriately.

In Summary

Plugin version numbers should tell you everything you need to know about what’s expected to change in the next release.

In addition, you should probably implement a changelog to show your users exactly what is changing with the current version.

Just to recap:

1. Update your MAJOR version when you make non-backwards compatible changes
2. Update your MINOR version when you add features (and fix bugs)
3. Update your PATCH version when the release only contains bug fixes

I hope this helps you the next time you release a version of your plugin.