How to set the production version for a python package using pbr

Question

for my package, I have the following setup.py

import setuptools


setuptools.setup(
    setup_requires=['pbr>=2.0.0'],
    pbr=True
)

when I run python setup.py sdist, the version that gets tagged to the tar file is module-0.0.1.dev1207. If I modify the setup.cfg to have the following entry

[metadata]
version = 1.0.1

the version that gets tagged to the tar file is -1.0.1.dev1207.

I did some readings into pbr and saw that it uses the git commits and tags to create its versioning.

On their documentation, it states that

Versions can be managed two ways - postversioning and preversioning. Postversioning is the default, and preversioning is enabled by setting version in the setup.cfg metadata section. In both cases version strings are inferred from git.

If the currently checked out revision is tagged, that tag is used as the version.

If the currently checked out revision is not tagged, then we take the last tagged version number and increment it to get a minimum target version.

We then walk git history back to the last release. Within each commit we look for a Sem-Ver: pseudo header, and if found parse it looking for keywords. Unknown symbols are not an error (so that folk can’t wedge pbr or break their tree), but we will emit an info level warning message. Known symbols: feature, api-break, deprecation, bugfix. A missing Sem-Ver line is equivalent to Sem-Ver: bugfix. The bugfix symbol causes a patch level increment to the version. The feature and deprecation symbols cause a minor version increment. The api-break symbol causes a major version increment.

If postversioning is in use, we use the resulting version number as the target version.

If preversioning is in use we check that the version set in the metadata section of setup.cfg is greater than the version we infer using the above method. If the inferred version is greater than the preversioning value we raise an error, otherwise we use the version from setup.cfg as the target.

We then generate dev version strings based on the commits since the last release and include the current git sha to disambiguate multiple dev versions with the same number of commits since the release.

But that makes me unsure about the following questions:

1. How can I enable preversioning?
2. What if there was never a tag or in the repo since pbr seems to say that at least one of them is necessary for pbr to work correctly?
3. How can I remove the dev1207 part of my version?
4. How can I setup the setup.cfg to read the version from my main.py instead of me having to specify it in the setup.cfg file?

Answer 1

Preversioning and postversioning are enabled in PBR by default, and based on string semantics. More info on the latest SemVer versioning standard can be found here.

I think what you are looking for, though, is how to update the version from git. To do that simply add a tag with a SemVer string, for example v1.0.1 or even just 1.0.1. Other options - see SemVer documentation above.

PBR will use the latest tag it can find - I believe in the currently checked out branch. If it doesn't find a valid tag (which seems to be the case for your repo), it certainly appears to first default to 0.0.1, but also appears to revert to using the version string in the metadata in setup.cfg.

Once it has that version, if there are any commits made after the last tagged version, it appends a .devN postfix to the version string, incrementing it for every untagged commit.

So, I'm guessing you have a large master branch that has 1209 commits, but no tags? Something like that, anyway.

Just start tagging your commits when you have a release, or stick with the devN style releases. It's really up to you.