0

In a web app I am building, I might finish two distinct minor features at the same time: Implementation of a new web page, and implementation of the notification bar. After merging both of these into master on GitHub, and resolving any existing conflicts, I will release it.

My current release is v0.9.1

When I release again, there will be two new minor changes. Would it become 0.11.0, 0.10.0? The https://semver.org does not seem to give any insight on this scenario.

Note: I would ask this on webapps SE but semantic versioning does not have its own tag. It seemed more likely to get an answer on this site.

Marvin
  • 195
  • Are you actually planning to make two public releases, one of which only has one of the changes? – 8bittree Jul 17 '19 at 14:19
  • I don't know what is best, which is why I am asking this question – Marvin Jul 17 '19 at 15:11
  • You might check this out since you are using Git: https://jeffkreeftmeijer.com/git-flow/ and for a more detailed discussion: https://nvie.com/posts/a-successful-git-branching-model/ – Berin Loritsch Jul 17 '19 at 16:03

1 Answers1

6

TL;DR:

  • For a release with new features that don't change behaviour of any existing features, increment the minor (Y in x.Y.z) version by one.
  • For breaking changes (especially where an automated workflow or API consumer would be affected) semantic versioning states you must increment the major (X) version.
  • When you do releases, always increment the version numbers by one, regardless of how many fixes/features go into the release

Semantic Versioning is really about APIs and backwards compatibility:

  1. Software using Semantic Versioning MUST declare a public API.

If you are trying to follow it for general purpose software (eg, not necessarily an API) you have to take a bit of a looser interpretation. All it says on incrementing for new features is:

  1. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API.

    It MAY be incremented if substantial new functionality or improvements are introduced within the private code.

  2. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

So basically if you're not changing any existing functionality (breaking backwards compatibility) then it's appropriate to increment the minor version.

Increment

It also only talks about "increment" and doesn't specify count, but every project I've ever come across increments by one, regardless of how much goes in. If you were to try to increment by the number of features you introduce in a single release, you cause two pointless problems: (1) debate about how to count "features", and (2) you end up with versions that look like 1.55.0, 1.92.0, 1.101.0, etc.

What's a 'release'?

As far as how many features go into a release, that's more art than science. There's usually a few factors involved, including:

  • If the new features are related or dependent on each other
  • How much time has passed since the last release
  • How much longer will it take to finish the remaining features
  • If there is someone or something waiting for a specific feature (another product, specific user(s), etc)
  • If you want a release to generate publicity/interest/etc
  • How much work/pain it is for you to do a release, and your users to upgrade (high effort upgrades + many release = unhappy users)

Major Versions

For general software, there's also often an artificial increment of the major version, even if the release is not backwards-incompatible -- releasing 2.0 simply makes a bigger "splash" than releasing 1.19.0. This is really just a judgement call, and unless there really is a major backwards-incompatible change, it has more to do with marketing than anything technical.

If you have a release that introduces significant new features but maintains backwards compatibility and you increment the major version anyway, you'll get basically no complaints (at least none worth listening to) about not strictly following semantic versioning.

Community
  • 1
gregmac
  • 847
  • These are two distinct features, but you advised to only increment by one. Since I am still in pre-release, I release every week. The day has not come where I release again, and because I will continue this organized procedure of releasing, I will have both distinct features finished by the next release date. – Marvin Jul 17 '19 at 16:13
  • Also, this is a web app so the users do not upgrade, it automatically updates for them when I upload all the files to the public server – Marvin Jul 17 '19 at 18:34
  • I'm not understanding your comments @Marvin, the answer is that the number of features you add/change/remove in the release doesn't affect the release number, regardless of how significant or distinct the features are. Have you looked at SemVer'd opensource projects? They typically have a changelog that shows the (often many) changes that are encapsulated in a single release. – Paul Jul 17 '19 at 19:01
  • So it should become 0.10.0? – Marvin Jul 17 '19 at 19:03
  • If you're doing a single deployment web app (eg, you don't have users hosting their own versions of your app) then the version number of the app itself becomes really unimportant. It's good to have a district number so you can identify what code is running on your server (useful for troubleshooting), but none of your users will care. Do whatever you like that's easy to track. Personally for apps like that, I usually just have 1.0.build_number where build_number is just the auto-increment number my CI server generates on every build. – gregmac Jul 17 '19 at 19:52
  • Where SemVer could come into play with a web api is the actual public REST/SOAP/GraphQL/whatever API, if there is one, but in that case the API version is actually separate from the application version, because usually you'd keep older version APIs accessible for quite a while. This is essential to allow developers consuming that API to update and deploy their own apps on their own frequency. As far as SemVer + web APIs, I'd say only the major.minor version matters, and in many cases it's just major -- as an API consumer, I just don't want my app to break when you deploy an update. – gregmac Jul 17 '19 at 20:04