| 1 |
=============================== |
| 2 |
Notes for Package maintainers |
| 3 |
=============================== |
| 4 |
|
| 5 |
If you are maintaining packages of software that uses *pbr*, there are some |
| 6 |
features you probably want to be aware of that can make your life easier. |
| 7 |
They are exposed by environment variables, so adding them to rules or spec |
| 8 |
files should be fairly easy. |
| 9 |
|
| 10 |
Versioning |
| 11 |
---------- |
| 12 |
|
| 13 |
*pbr*, when run in a git repo, derives the version of a package from the |
| 14 |
git tags. When run in a tarball with a proper egg-info dir, it will happily |
| 15 |
pull the version from that. So for the most part, the package maintainers |
| 16 |
shouldn't need to care. However, if you are doing something like keeping a |
| 17 |
git repo with the sources and the packaging intermixed and it's causing pbr |
| 18 |
to get confused about whether its in its own git repo or not, you can set |
| 19 |
``PBR_VERSION``: |
| 20 |
|
| 21 |
:: |
| 22 |
|
| 23 |
export PBR_VERSION=1.2.3 |
| 24 |
|
| 25 |
and all version calculation logic will be completely skipped and the supplied |
| 26 |
version will be considered absolute. |
| 27 |
|
| 28 |
Distribution version numbers |
| 29 |
---------------------------- |
| 30 |
|
| 31 |
*pbr* will automatically calculate upstream version numbers for *dpkg* and |
| 32 |
*rpm* using systems. Releases are easy (and obvious). When packaging |
| 33 |
pre-releases though things get more complex. Firstly, semver does not provide |
| 34 |
for any sort order between pre-releases and development snapshots, so it can be |
| 35 |
complex (perhaps intractable) to package both into one repository - we |
| 36 |
recommend with either packaging pre-release releases (alpha/beta/rc's) or dev |
| 37 |
snapshots but not both. Secondly, as pre-releases and snapshots have the same |
| 38 |
major/minor/patch version as the version they lead up to, but have to sort |
| 39 |
before it, we cannot map their version naturally into the rpm version |
| 40 |
namespace: instead we represent their versions as versions of the release |
| 41 |
before. |
| 42 |
|
| 43 |
Dependencies |
| 44 |
------------ |
| 45 |
|
| 46 |
As of 1.0.0 *pbr* doesn't alter the dependency behaviour of *setuptools*. |
| 47 |
|
| 48 |
Older versions would invoke *pip* internally under some circumstances and |
| 49 |
required the environment variable ``SKIP_PIP_INSTALL`` to be set to prevent |
| 50 |
that. Since 1.0.0 we now document that dependencies should be installed before |
| 51 |
installing a *pbr* using package. We don't support easy install, but neither |
| 52 |
do we interfere with it today. If you observe easy install being triggered when |
| 53 |
building a binary package, then you've probably missed one or more package |
| 54 |
requirements. |
| 55 |
|
| 56 |
.. important:: |
| 57 |
|
| 58 |
We reserve the right to disable easy install via *pbr* in future, since we |
| 59 |
don't want to debug or support the interactions that can occur when using |
| 60 |
it. |
| 61 |
|
| 62 |
.. _packaging-tarballs: |
| 63 |
|
| 64 |
Tarballs |
| 65 |
-------- |
| 66 |
|
| 67 |
*pbr* includes everything in a source tarball that is in the original *git* |
| 68 |
repository. This can again cause havoc if a package maintainer is doing fancy |
| 69 |
things with combined *git* repos, and is generating a source tarball using |
| 70 |
``python setup.py sdist`` from that repo. If that is the workflow the packager |
| 71 |
is using, setting ``SKIP_GIT_SDIST``: |
| 72 |
|
| 73 |
:: |
| 74 |
|
| 75 |
export SKIP_GIT_SDIST=1 |
| 76 |
|
| 77 |
will cause all logic around using git to find the files that should be in the |
| 78 |
source tarball to be skipped. Beware though, that because *pbr* packages |
| 79 |
automatically find all of the files, most of them do not have a complete |
| 80 |
``MANIFEST.in`` file, so its possible that a tarball produced in that way will |
| 81 |
be missing files. |
| 82 |
|
| 83 |
.. _packaging-authors-changelog: |
| 84 |
|
| 85 |
AUTHORS and ChangeLog |
| 86 |
--------------------- |
| 87 |
|
| 88 |
*pbr* generates ``AUTHORS`` and ``ChangeLog`` files from *git* information. |
| 89 |
This can cause problem in distro packaging if package maintainer is using *git* |
| 90 |
repository for packaging source. If that is the case setting |
| 91 |
``SKIP_GENERATE_AUTHORS`` |
| 92 |
|
| 93 |
:: |
| 94 |
|
| 95 |
export SKIP_GENERATE_AUTHORS=1 |
| 96 |
|
| 97 |
will cause logic around generating ``AUTHORS`` using *git* information to be |
| 98 |
skipped. Similarly setting ``SKIP_WRITE_GIT_CHANGELOG`` |
| 99 |
|
| 100 |
:: |
| 101 |
|
| 102 |
export SKIP_WRITE_GIT_CHANGELOG=1 |
| 103 |
|
| 104 |
will cause logic around generating ``ChangeLog`` file using *git* |
| 105 |
information to be skipped. |
| 106 |
|
| 107 |
.. _packaging-releasenotes: |
| 108 |
|
| 109 |
Release Notes |
| 110 |
------------- |
| 111 |
|
| 112 |
*pbr* generates a release notes file, typically called ``RELEASENOTES.rst``, |
| 113 |
if `reno`_ is present and configured. You may wish to disable this |
| 114 |
functionality. If that is the case setting ``SKIP_GENERATE_RENO`` |
| 115 |
|
| 116 |
:: |
| 117 |
|
| 118 |
export SKIP_GENERATE_RENO |
| 119 |
|
| 120 |
will disable this feature. |
| 121 |
|
| 122 |
.. _reno: https://docs.openstack.org/reno/latest/ |