diff options
Diffstat (limited to 'doc/source/index.rst')
| -rw-r--r-- | doc/source/index.rst | 56 |
1 files changed, 49 insertions, 7 deletions
diff --git a/doc/source/index.rst b/doc/source/index.rst index f4d604e..f36fc6f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -26,11 +26,37 @@ PBR can and does do a bunch of things for you: Version ------- -Version strings will be inferred from git. If a given revision is tagged, -that's the version. If it's not, and you don't provide a version, the version -will be very similar to git describe. If you do, then we'll assume that's the -version you are working towards, and will generate alpha version strings -based on commits since last tag and the current git sha. +Versions can be managed two ways - postversioning and preversioning. +Postversioning is the default, and preversioning is enabeld by setting +``version`` in the setup.cfg ``metadata`` section. In both cases +version strings are inferred from git. + +If a given revision is tagged, that's the version. + +If it's not, 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 - that is if there is a version set in setup.cfg +metadata - then we check that that version is higher than the target version +we inferred above. If it is not, 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. .. note:: @@ -39,6 +65,11 @@ based on commits since last tag and the current git sha. The versions are expected to be compliant with :doc:`semver`. +The ``version.SemanticVersion`` class can be used to query versions of a +package and present it in various forms - ``debian_version()``, +``release_string()``, ``rpm_string()``, ``version_string()``, or +``version_tuple()``. + AUTHORS and ChangeLog --------------------- @@ -76,11 +107,21 @@ You can also have a requirement file for each specific major version of Python. If you want to have a different package list for Python 3, just drop a requirements-py3.txt, and it will be used instead. +It's also possible to select a requirement file specific for an OS. The format +is requirements-{osname}.txt, where ``{osname}`` is the equivalent of +``platform.system()``. The two approaches, Python version and OS version, can +be combined. + The requirement files are tried in that order (N being the Python major -version number used to install the package): +version number used to install the package and OS being the current +platform's name in lowercase, retrieved with ``platform.system()``): +* requirements-OS-pyN.txt +* tools/pip-requires-OS-pyN +* requirements-OS.txt +* tools/pip-requires-OS * requirements-pyN.txt -* tools/pip-requires-py3 +* tools/pip-requires-pyN * requirements.txt * tools/pip-requires @@ -221,6 +262,7 @@ Additional Docs packagers semver + testing Indices and tables ================== |