How to increment a version depending on the commit history since last tag?

Question

Incrementing a version by SemVer might be a matter of taste but surely it has its boundaries which I couldn't find by research. I thought about a way to increment my version depending on the git commit history since the last tag. Please verify my statement or provide me with alternatives.

Given

• last-tag: v0.0.1
• master: master branch of the git history
• release: release branch of the git history
• B: Breaking-Change/Major
• M: Minor Change
• F: Fix/Patch

Example #1

     v0.0.1         (v0.1.0)  (v0.1.1)   v0.1.1
master  o--o--------------------------------o----->
release     \______________________________/
              |      |  |         |
              F      M  M         F
              1      1  2         2

The commit history holds two fixes (F) and two minor changes (M). Everything before the second minor change (M2) is considered to be grouped as a minor change because there isn't any higher change, like a breaking change (B), before it.

Here is where I add +1 to the minor version: v.0.1.0

However after the last highest change (M2) there is a fix change (F2). This one is considered as a patch change depending on the last minor change (v0.1.0).

Therefore this fix change will increment the patch version by 1: v0.1.1

     v0.0.1   (v1.0.0)  (v1.1.0)  (v1.1.1)        v1.1.1
master  o--o------------------------------------------o----->
release     \________________________________________/
              |   |  |      |         |
              F   B  M      M         F
              1   1  1      2         2

Another example where a breaking change (B1) is dominating as the highest version. However all following version still depend on that breaking change and are allowed to increment because of their semantic value for the version.

First the major change will increment to v1.0.0 and grouping both minor changes (M1 & M2) to one minor change increment will result in v1.1.0. In the end there is still a fix/patch change left depending on either the minor changes (M1 & M2) or the major/breaking change (B1). This will increment the patch version by 1 to finally: v1.1.1

Example #2

     v0.0.1         (v0.1.0)             v0.1.0
master  o--o--------------------------------o----->
release     \______________________________/
              |      |  |         |
              F      M  M         F
              1      1  2         2

In this case only the highest change will be considered as the one who does affect the version number regardless of the chronological order of the changes.

The highest change is a minor change (M1 | M2) so the version will be incremented by 1: v0.1.0 It does not matter if the fix (F2) afterwards semantically depends on the last minor change (M2) even tho it might have patched/fixed a feature added by the last minor change (M2)

     v0.0.1   (v1.0.0)                  v1.0.0
master  o--o-------------------------------o----->
release     \_____________________________/
              |   |   |  |         |
              F   B   M  M         F
              1   1   1  2         2

Another example where a breaking change (B1) would dominate all other versions since it's the highest/most relevant change.

Question

Is there a best practice on how to increment versions depending on the change types? Are both ways valid or is one of them the convention of SemVer?

Answer 1

So you are essentially asking whether eliding less significant fields in higher field bumps is acceptable? As-in 0.0.x to 1.0.0 even though there were lots of minor and patch level changes made leading up to or following the major bump? The answer is yes it is acceptable. SemVer references releases or prereleases, it does not reference every little change made to the code. The algorithm is quite simple:

• For each successful release/prerelease build
  • Bump the most significant version field that applies.

This helps reduce the number of gaps in the publicly visible sequence of versions and allows spelunkers to spot versions that have been removed from public feeds. In practice, such feeds are full of gaps anyway, because we generally flight test nearly every CI build in some form or another so we churn through most of the available version numbers along the way and only leave the most important milestones visible in the feeds.

If you need further clarification please ask, I'll be happy to try and answer any questions.