setup_scmversion

Builds a semantic version number based on information available on your scm (tag, branch, and number of commits).

See LICENSE for important licensing information.

Instalation

pip install jfaleiro.setup-scmversion

Or as a dev dependency in poetry:

poetry add jfaleiro.setup-scmversion --dev
poetry update

Currently only git is supported.

Use

A semantic version number is created from standard data available in your scm, i.e. tag, branch name, and number of commits from a tag or master. It supports a simple workflow:

• Versions follow a simplified semantic versioning scheme.
• Non-production releases are produced from release branches named release/<version>.
• Non-production releases are produced from feature-releases named feature/<version>.
• Production releases and releases candidates are generated from a tag in master after a release branch is merged to master. The version will match the tag.

Simplest Use

Should apply to most projects. Tag the current version before build or deploy using a command line:

$ scmversion version
0.1.1

V=`scmversion version`
echo
0.1.1

or the type of version:

$ scmversion version-type
RELEASE_BRANCH

The type of version can be one of RELEASE, RELEASE_BRANCH, FEATURE_BRANCH, or OTHER.

or even replacing version variables in files. Take for example a this file pyproject.template.toml:

...
[tool.poetry]
name = "jfaleiro.setup-scmversion"
version = "${POETRY_VERSION}"
description = 'Semantic version number based on scm tags and branches'
...

scmversion tag-file --version POETRY_VERSION --pre-commit pyproject.template.toml pyproject.toml

will have a resulting file:

...
[tool.poetry]
name = "jfaleiro.setup-scmversion"
version = "0.1.1"
description = 'Semantic version number based on scm tags and branches'
...

And many more. Refer to the command line help for details.

$ scmversion --help
usage: scmversion [-h] {version,version-type,parsers,tag-version,generate-setup,tag-file,show,check} ...

Version parser from scm

positional arguments:
  {version,version-type,parsers,tag-version,generate-setup,tag-file,show,check}
    version             displays the version
    version-type        displays the version type (one of ['RELEASE', 'RELEASE_BRANCH', 'FEATURE_BRANCH', 'OTHER'])
    parsers             lists all parsers available
    tag-version         tags a python package with a version file
    generate-setup      generates a setuptools compatible setup.py file
    tag-file            tags a file with version and type
    show                show what is currently tagged
    check               asserts versions on version file and scm are the same

optional arguments:

Pre-commit

For use as a pre-commit hook add this to your .pre-commit-config.yaml for example:

  - repo: https://gitlab.com/jfaleiro.open/setup_scmversion
    rev: 0.1.1
    hooks:
      - id: tag-version
      - id: tag-pyproject
      - id: tag-readme

Versioning Schema

• Release branches release/<version> with nnn differences from master will produce a RELEASE_BRANCH with a version <version>-dev<nnn>
• Feature branches feature/<version> with nnn differences from master will produce a FEATURE_BRANCH with a version <version>-feature<nnn>
• A well-formed tagged version <tag> on master will produce a RELEASE version <tag>.
• Everything else will produce 0.0.0+master... for master or 0.0.0+other... for any other branch.