vcver 0.0.3

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

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

Special Thanks

• Zillow, where this approach of SCM-based versioning started

• 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