Git tag release version?

Question

A pre-release version MAY be denoted by appending a dash and a series of dot separated identifiers immediately following the patch version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

semver.org

For the purpose of disambiguation, what would be a "proper" way to tag a release commit (commit from the master branch)?

Some ideas

v1.7.2-release
v1.7.2-master
v1.7.2-prod
v1.7.2-official
v1.7.2-stable

github.com/antirez/redis/tags

Solution

You can choose a policy similar to Git itself (see its tags in the GitHub repo):

v1.7.2-rc0
v1.7.2-rc1
v1.7.2-rc2
v1.7.2-rc3
v1.7.2

The idea (as described in Choosing a good version numbering policy) can go along the lines of:

The ‘master’ branch will be the one containing the code marked to be production ready in a given moment, ‘master’ must be always compilable.
Code in the ‘master’ branch must have an even tag number.

For the version number, it will be created using the git describe command, since it’s a sort of standard de facto.

See Canonical Version Numbers with Git:

git describe –tags –long

This gives you a string like (in the case of one of my projects)

2.1pre5-4-g675eae1

which is formatted as

{last reachable tag name}-{# of commits since that tag}-#{SHA of HEAD}

This gives you a ‘canonical version number’ (spelling corrected) that is monotonically increasing by commits, and unique across multiple repositories of development. If we’re all on the same HEAD, it will return the same value. If we all share the same most-recent-tag, but have different commits, the SHA will be different.

You can strive for having on master only version numbers like

{last reachable tag name}-0-#{SHA of HEAD}

(ie tagged commits only)

But the idea is that this kind of version number (tag + SHA) is completely unambiguous.