tl;dr - You already partly do it, just with different semantics to what the rest of us follow. Following semver strictly would give value to the main developer audience.

There are many different ways that software releases can be versioned - by name, by release date, by sequential integer, by some complex string of numbers that include internal build number / time and so on.

Sometimes releases may appear to be numerical, but turn out to be strings, when numbers are skipped over for technical reasons i.e. Windows 9, and PHP 6.

These version identifiers are aimed at different groups of users, but broadly, the less complex ones (e.g. names, like High Sierra, and Windows 10) are aimed at Users. The others with numbers are more aimed at developers - either developers of that software or developers who consume / develop against that software.

CMB2 is typically aimed at a developer audience.

To ensure compatibility, developers have to understand what the version means - a date or name-based version misses out on an opportunity to let developers know if there was any significant change or whether it was simply one or more bug fixes. That means consumers have to read all of the change log to avoid any nasty surprises.

You know where this is heading, but Semantic Versioning (semver) is the de facto standard that for the majority of packages, at least in the PHP / WP space, can and do follow. Read the spec if you aren't familiar.

The question, is what versioning system CMB2 uses, and whether anything can be gleaned from it.

There are 38 releases for this repo, but 9 of them have a version number less than 2.0.0. That means there have been 29 releases to get from 2.0.0 to 2.2.6.1.

Let's look at the release versions from latest, going backwards. E indicates that an enhancement was added, and B indicates a bug was fixed (according to the release notes):

• 2.2.6.1 EB
• 2.2.6 EB
• 2.2.5.3 EB
• 2.2.5.2 B
• 2.2.5.1 B
• 2.2.5 EB
• 2.2.4 EB
• 2.2.3.1 EB
• 2.2.3 EB
• 2.2.2.1 B
• 2.2.2 EB
• 2.2.1 B
• 2.2.0 EB
• 2.1.2 B
• 2.1.1 EB
• 2.1.0 B
• 2.0.9 EB
• 2.0.8 B
• 2.0.7 EB (including breaking change)
• 2.0.6 EB
• 2.0.5 B
• 2.0.4 B
• 2.0.3 EB
• 2.0.2 E
• 2.0.1 EB
• Various 2.0.0.* as beta releases.

First off is to note that in the last few releases, there is an inconsistent format of the version string itself - sometimes it's a.b.c, and others it's a.b.c.d. The a.b.c format is implicitly equal to a.b.c.0.

There are two patterns which indicate at least an underlying effort to follow semver:

• The "hotfix releases" (with the non-zero d part) tend to be bug-fix releases, though a couple of enhancements have also sneaked in. This extra .1 implies a connection to the implicit .0, even if it's down at the d level.
• There was a jump between 2.1.2 and 2.2.0, so despite 2.1.0 coming after 2.0.9 (indicative of not following semver), something in that 2.2.0 release suggested it was worth skipping over the rest of the 2.1.* versions (a good thing).

In all cases, a is typically 2, due to the project's history, and that does make the use of semver for this project less clear-cut than other packages.

One obvious point where semver has not been followed is the documented breaking change for 2.0.7.

As with any software, the aim is not to break backwards compatibility (BC). Or, more specifically, it should not break BC accidentally / without a clear indicator. Having it just buried within release notes / changelog is not sufficient.

Let's assume that at some point in the next year or two, WP bumps the minimum required version of PHP to 5.4.

Let's even allow an overly-generous five-year lag before namespaces are allowed to be used in CMB2. At whichever point in time that will be, the switch to namespaces is going to break BC, and at that point, theme and plugin developers will need to know that.

Releases that identify as having breaking changes are a necessary part of software development. They allow for changes in public API for better long-term usage, the removal of old deprecated code that adds to maintenance, and generally, is a chance to reduce technical debt - as an example think of the simplified code if PHP 7 was the minimum required version, and what scalar type declarations could do.

Let's take the above list of releases since the v2 betas to see what that would look like if semver had been followed. (For the purposes of this first example, I'm actively going to ignore the breaking change):

• 2.15.0 EB
• 2.14.0 EB
• 2.13.0 EB
• 2.12.2 B
• 2.12.1 B
• 2.12.0 EB
• 2.11.0 EB
• 2.10.0 EB
• 2.9.0 EB
• 2.8.1 B
• 2.8.0 EB
• 2.7.1 B
• 2.7.0 EB
• 2.6.1 B
• 2.6.0 EB
• 2.5.1 B
• 2.5.0 EB
• 2.4.1 B
• 2.4.0 EB (including breaking change)
• 2.3.0 EB
• 2.2.2 B
• 2.2.1 B
• 2.2.0 EB
• 2.1.0 E
• 2.0.0 EB
• Various 2.0.0-beta as beta releases.

And now, including the breaking change:

• 3.11.0 EB
• 3.10.0 EB
• 3.9.0 EB
• 3.8.2 B
• 3.8.1 B
• 3.8.0 EB
• 3.7.0 EB
• 3.6.0 EB
• 3.5.0 EB
• 3.4.1 B
• 3.4.0 EB
• 3.3.1 B
• 3.3.0 EB
• 3.2.1 B
• 3.2.0 EB
• 3.1.1 B
• 3.1.0 EB
• 3.0.1 B
• 3.0.0 EB (including breaking change)
• 2.3.0 EB
• 2.2.2 B
• 2.2.1 B
• 2.2.0 EB
• 2.1.0 E
• 2.0.0 EB
• Various 2.0.0-beta as beta releases.

I'm not sure what concerns there are about using semver, but one often touted is that version numbers will get massive. That doesn't seem to concern Chrome (currently v62) and Firefox (v57), but as can be seen, the whole not-quite-3-years of CMB2 would only have got up to 2.15.0 or 3.11.0. Would developers be less inclined to use it because of that? I doubt it - more likely, they would be more appreciative of the project, because it followed semver.

As mentioned in the tweet that elicited the invite to open this issue - an intention not to break BC doesn't mean you can't follow semver; it has other value for the target audience for BC-compatible enhancements and bug-fix releases.

Based on all of this, I would propose two things:

• Treat "CMB2" and its expanded form as the marketing name. Users don't really care for version numbers, so while "CMB2 v3.1.4" may seem a little odd at first, Users will be fine with it. However, Developers can get value from understanding what a 3.1.4 release might have compared to the 3.1.3, 3.0.8 and 2.18.5 releases.
• Switch to use semver strictly. Put out bug-fix only releases as a bump to the patch level (c in our example, or z in the semver document), and any addition of an enhancement automatically means the minor release (b in our example, or y in the semver document) is bumped.