What is vcver?

vcver is an approach for versioning that heavily relies on the version control system of choice for determining version strings.

There are two categories of version strings:

develop versions, of the form:

{main_version}.dev{commit_count}+{branch}.{scm_change_id}

With development branches, it is desired to not override versions published from a blessed subset of “released” branches. As such, if the current branch is not a release branch, a version of 0 is used instead of the main_version:

0.dev{commit_count}+{branch}.{scm_change_id}

and a release version, of the form:

{main_version}

Each part is described as follows:

• main_version is retrieved from the last tagged commit with a leading v (e.g. v1.0), but is converted to a 0 if the branch is not a release branch.

• commit_count is the number of commits from main_version

• branch is the branch that the repository was built against, removing characters that are incompatible with PEP440 (anything that is not alphanumeric or a dot)

• scm_change_id is a unique id in the form of version control, used to identify the change that was used to build this version.

For example, in a git repository, on a master branch with the most recent tag of v1.1, the dev version would look something like:

1.1.dev10+master.abc123

On a develop branch:

0.dev13+develop.def456

And a release version:

1.1

These are compatible with PEP440.

Example

Add a MANIFEST.in to your package, if you do not already have one. Then add the following:

include VERSION

It’s also recommended to ignore this file in your version control.

Then, follow this pattern in your setup.py:

# OPTIONAL, but recommended:
# this block is useful for specifying when a build should
# use the 'release' version. it allows specifying a release version
# with an additional argument in the setup.py:
# $ python setup.py upload --release
import sys
is_release = False
if "--release" in sys.argv:
    sys.argv.remove("--release")
    is_release = True

# OPTIONAL, but recommended:
# vcver writes a version file relative to the
# current working directory by default.
# It's recommended to provide it with your
# setup.py directory instead (in case someone
# runs your setup.py from a different directory)
base = os.path.dirname(os.path.abspath(__file__))

setup(name='aiohttp-transmute',
    # add the following two lines,
    # and do not specify a version.
    setup_requires=["vcver"],
    # vcver will only produce a release
    # version if "is_release" is True.
    vcver={
        "is_release": is_release,
        "path": base,
        # OPTIONAL ARGS

        # version_format overrides the standard version format
        version_format="{main_version}.{commit_count}",

        # release_version_format overrides the release version format
        release_version_format="{commit_count}",

        # scm_type: if you do not want autodetection of the SCM, you can
        # specify it.
        scm_type="git",

        # release_branch_regex: override the default release branch
        # (default release branch depends on the SCM used.)
        release_branch_regex="(master|hotfix|release)",

        # version_file: override the name of the version file.
        version_file="GENERATED_VERSION"
    },
    ...
)

Now your package will publish with a VC-based version!

If you followed the full example, you can specify the release version by adding –release:

python setup.py upload --release

FAQ / Other Details

include VERSION

     {main_version}.dev{commit_count}.{branch}.{scm_change_id}

This can be changed by an argument into vcver:

# in the setup call of setup.py
vcver={"version_format": "{main_version}.dev{commit_count}.{branch}.{scm_change_id}"}

Special Thanks

• Zillow, where this particular approach of SCM-based versioning was developed

• Taylor McKay, who implemented the original Python version at Zillow

• Mohammad Sarhan, who designed and implemented the original Java version at Zillow, and has a public gradle variant