Versioning Semantic Versioning – When and How to Do a Release?

semantic-versioningversioning

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?

Best Answer

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.

Related Topic