Software Versioning Scheme + Human Readable Version + Semantic Versioning (SemVer) with `git describe`

Software-Versioning-Scheme.md

Software Versioning

Scheme

1.2.3[-beta.1][+123] → major.minor.patch[-pre-release][+build]
| | |    |      |
| | |    |      +-- build:        optional dot-separated build identifiers
| | |    +--------- pre-release:  optional dot-separated pre-release identifiers build metadata information
| | +-------------- hotfix:       make backwards-compatible bug fixes
| +---------------- feature:      add functionallity in backwards-compatible manner
+------------------ main version: changes to the API result in incompatibility to prior versions

References

• Software versioning - Wikipedia
• Semantic Versioning

Version-From-Git.md

git-describe - a human readable version number

git describe

To get a human readable version from git, you can use the git-describe command.

$ git describe --tags
2.1.1-7-g6176ca9

Semantic Versioning 2.0.0

To follow the SemVer rules use the following command, if git describe should be the source of your version.

$ git describe --tags | sed -r 's/([0-9]+\.?)-([0-9]+)-(.+)/\1-\2\.\3/g'
2.1.1-7.g6176ca9

Scheme

2.1.1[-7.g6176ca9] → {most-recent-tag}[-{number-of-additional-commits}[-|.]{abbreviated-object-name}]
  |   |||    |
  |   |||    +----- abbreviated object name of the most recent commit
  |   ||+---------- dot (SemVer) or hyphen (git describe) as seperator in pre-release
  |   |+----------- number of additional commits on top of the tagged object
  |   +------------ pre-release seperator (hyphen), followed by dot-separated pre-release identifiers
  +---------------- most recent tag that is reachable from a commit

Example

The following example is used for an application, hosted on GitLab and deployed to Googles App Engine.

Dots are permitted in Googles App Engine version names in the console (as of 2020-04-23), so you have to replace dots with a hyphen (sed -r 's/\./\-/g'). The application version in myapp/version.py is kept with dots as returned from git describe.

Excerpt of .gitlab-ci.yml

image: google/cloud-sdk:alpine

before_script:
  - apk add gettext
  - export APP_VERSION_SEMVER=`git describe --tags | sed -r 's/([0-9]+\.?)-([0-9]+)-(.+)/\1-\2\.\3/g'`
  - export APP_VERSION=`echo $APP_VERSION_SEMVER | sed -r 's/\./\-/g'`
  - echo __version__=\'$APP_VERSION_SEMVER\' > papa/__init__.py
  - echo $SERVICE_ACCOUNT > /tmp/$CI_PIPELINE_ID.json
  - envsubst < app.yaml.template > app.yaml
  - gcloud auth activate-service-account --key-file /tmp/$CI_PIPELINE_ID.json
  
deploy_dev:
  stage: deploy
  environment:
    name: development
    url: https://myapp.appspot.com/api/doc
  only:
  - develop
  script:
  - gcloud --quiet --project $PROJECT_ID app deploy --version $APP_VERSION

version.py

""" Get the current application version from git describe """

import subprocess


def get_version():
    return subprocess.check_output(['git', 'describe']).strip().decode('utf-8')


__version__ = get_version()