7

Scenario
I have a plugin for CakePHP 3, which I am working on and people are submitting bugs for it. I have an active development branch in develop to which I send pull requests from fix branches.

I am using the semantic versioning standard for versioning my plugin.

When should I release?
If I have three open bugs and I fix them one after the other, should I be making three releases? Or should I make a single release for all of these fixes?

How do multiple fixes impact my versioning?
In the above example I have three fixed bugs, so to me that means I should be increasing the PATCH version number by three. Is that correct, or is the version number specifically tied to the release. So, by pushing a single release I would only increment the PATCH version by one to indicate one bugfix release?

TL;DR
Does each fix count towards your versions PATCH number?

  • 1
    You might tell more about your plugin. A plugin for what? (you could change some version numbers when the host program changes the plugin API). Is you plugin free software? Then give its URL! So please edit your question to improve it. – Basile Starynkevitch Mar 17 '15 at 12:06
19

It's never explicitly spelled out, but careful reading of semver.org suggests that a version is associated with a proper release, not a VCS commit. So naturally, if you make one release that has multiple bug fixes, you increment the patch component once. Leaving large gaps to account for intermediate states that don't have a version (not even in principle, like broken releases that have been withdrawn) makes no sense.

You could of course make a release for every single tiny change, but this is probably not desirable: It's a lot of work for you, it wastes user's time and bandwidth with frequent updates, and it results in ludicrous version numbers and release logs. There are various policies for when to release, and which works best is mostly a matter of opinion and the quirks of the project and its user base. Some common options are:

  • Some project release once every X time units, regardless of how many or few changes were done.
  • Some projects release once a subjective threshold of "enough changes" is reached.
  • Some projects have milestones: "We'll release vX.Y once we have this thing and that thing done".
  • A mix of the above.

Most projects, even when they normally adhere to one of the above, can release out-of-line hot fixes when a particular nasty bug was released in the wild.

Conversely, if you put out new releases so rarely (or never) that most people just track git master, then you fail at semver because these people don't get any backwards compatibility guarantees. The fix is not to give each commit its own version number but to release in more sensible intervals.

5

Beware that if CakePHP 3 is changing its plugin API (and your plugin adapts to that change), you probably should increase your major number.

BTW, in MELT I am explicitly naming the version(s) of GCC for which that release is made. So I am naming them MELT-1.1.3 for GCC 4.8 or 4.9

Plugins are a corner-case of semantic versioning, because what usually matters is both the version of the plugin, and the (acceptable) version of the program using that plugin.

  • This is a great point. As CakePHP 3 is RC currently, I'm keeping my version 0.x.x, then I'll release 1.0.0 when CakePHP 3 gets it's official release. I'm hoping this will mitigate the plugin api changes requiring a major version increment. – David Yell Mar 17 '15 at 12:53

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.