Suggestion for semver tag and release convention to use `v1.1.1`

[dougnukem]

This is a minor nitpick but with semantic versioning in an SCM like git the standard advice says to name it v${major}.${minor}.${patch}

• https://semver.org/spec/v1.0.0.html#tagging-specification-semvertag

  This sub-specification SHOULD be used if you use a version control system (Git, Mercurial, SVN, etc) to store your code. Using this system allows automated tools to inspect your package and determine SemVer compliance and released versions.

  When tagging releases in a version control system, the tag for a version MUST be “vX.Y.Z” e.g. “v3.1.0”.

  The first revision that introduces SemVer compliance SHOULD be tagged “semver”. This allows pre-existing projects to assume compliance at any arbitrary point and for automated tools to discover this fact.

Ideally we could name the github releases and tag are:

• v1.1.0
• v1.1.1

In terms of release branches I think its fine to call it something like: releases/v1.1

• patch versions v1.1.0 and v1.1.1 are tagged from this release branch (and hotfixes can be cherry-picked on to this release branch)

You also could do a 'just-in-time' release branch model where the tag is done on master and only when you need to specifically hotfix do you create the release branch:

# need to hotfix release `v1.2.0`
$ git checkout tags/v1.2 -b releases/1.2
# cherry-pick some merge commit
$ git cherry-pick -m 1 xyzabc
# Update Docker label version etc
$ make version-bump-patch 
$ git commit -a -m "Update version to 1.2.1"
$ git tag v1.2.1

For docker image tags I think the convention for semver is to have the following combinations of tags:

• https://medium.com/@mccode/using-semantic-versioning-for-docker-image-tags-dfde8be06699

  
  # Assume version: 2.5.3

• cedrickrin/golang-action:latest - this is the most recent built docker image version (its fine to never include this as relying on :latest is bad practice)
• cedrickrin/golang-action:2 - relying on major version this should be pinned to latest major version and backwards compatible for any changes to minor/patch
• cedrickrin/golang-action:2.5 - relying on specific major/minor version
• cedrickrin/golang-action:2.5.3 - relying on specific absolute version

I think the ideal situation is users depend on a specific major version e.g. cedrickrin/golang-action:2 and get the benefit of passively upgrading for bug/security fixes in any minor/patch versions while depending on the major version not having any backwards incompatible changes.

[cedrickring]

So we keep the major.minor.patch versioning for Docker?

You also could do a 'just-in-time' release branch model where the tag is done on master and only when you need to specifically hotfix do you create the release branch:

Does GitHub support overwriting tags? So the Docker versioning could apply to GH aswell. You could specify only e.g. v2 in your main.workflow and get all the latest minors and patches too.

This maybe relates to this issue aswell: Can we add some script to automatically update the README.md when a new release happens? Something like: replace all vx.x.x with the latest version.

[dougnukem]

Yes you can overwrite the git tags to match that versioning scheme, but I think the best process is to treat tags as immutable, and just re-tag the same ones as vX.Y.Z

• v1.0.0
• v1.1.0
• v1.1.1

I think it'd could make sense to use the docker versioning scheme and force tags for minor/patch updates:

• v2
• v2.1

[dougnukem]

Also i think while it's in master the process should be that things are tagged/re-tagged as: v1.2.0-develop - indicating the "next" version that will be released

We can add that to the Makefile process and update Readme and Dockerfile accordingly.