123 lines
4.2 KiB
ReStructuredText
123 lines
4.2 KiB
ReStructuredText
===============================
|
|
Notes for Package maintainers
|
|
===============================
|
|
|
|
If you are maintaining packages of software that uses *pbr*, there are some
|
|
features you probably want to be aware of that can make your life easier.
|
|
They are exposed by environment variables, so adding them to rules or spec
|
|
files should be fairly easy.
|
|
|
|
Versioning
|
|
----------
|
|
|
|
*pbr*, when run in a git repo, derives the version of a package from the
|
|
git tags. When run in a tarball with a proper egg-info dir, it will happily
|
|
pull the version from that. So for the most part, the package maintainers
|
|
shouldn't need to care. However, if you are doing something like keeping a
|
|
git repo with the sources and the packaging intermixed and it's causing pbr
|
|
to get confused about whether its in its own git repo or not, you can set
|
|
``PBR_VERSION``:
|
|
|
|
::
|
|
|
|
export PBR_VERSION=1.2.3
|
|
|
|
and all version calculation logic will be completely skipped and the supplied
|
|
version will be considered absolute.
|
|
|
|
Distribution version numbers
|
|
----------------------------
|
|
|
|
*pbr* will automatically calculate upstream version numbers for *dpkg* and
|
|
*rpm* using systems. Releases are easy (and obvious). When packaging
|
|
pre-releases though things get more complex. Firstly, semver does not provide
|
|
for any sort order between pre-releases and development snapshots, so it can be
|
|
complex (perhaps intractable) to package both into one repository - we
|
|
recommend with either packaging pre-release releases (alpha/beta/rc's) or dev
|
|
snapshots but not both. Secondly, as pre-releases and snapshots have the same
|
|
major/minor/patch version as the version they lead up to, but have to sort
|
|
before it, we cannot map their version naturally into the rpm version
|
|
namespace: instead we represent their versions as versions of the release
|
|
before.
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
As of 1.0.0 *pbr* doesn't alter the dependency behaviour of *setuptools*.
|
|
|
|
Older versions would invoke *pip* internally under some circumstances and
|
|
required the environment variable ``SKIP_PIP_INSTALL`` to be set to prevent
|
|
that. Since 1.0.0 we now document that dependencies should be installed before
|
|
installing a *pbr* using package. We don't support easy install, but neither
|
|
do we interfere with it today. If you observe easy install being triggered when
|
|
building a binary package, then you've probably missed one or more package
|
|
requirements.
|
|
|
|
.. important::
|
|
|
|
We reserve the right to disable easy install via *pbr* in future, since we
|
|
don't want to debug or support the interactions that can occur when using
|
|
it.
|
|
|
|
.. _packaging-tarballs:
|
|
|
|
Tarballs
|
|
--------
|
|
|
|
*pbr* includes everything in a source tarball that is in the original *git*
|
|
repository. This can again cause havoc if a package maintainer is doing fancy
|
|
things with combined *git* repos, and is generating a source tarball using
|
|
``python setup.py sdist`` from that repo. If that is the workflow the packager
|
|
is using, setting ``SKIP_GIT_SDIST``:
|
|
|
|
::
|
|
|
|
export SKIP_GIT_SDIST=1
|
|
|
|
will cause all logic around using git to find the files that should be in the
|
|
source tarball to be skipped. Beware though, that because *pbr* packages
|
|
automatically find all of the files, most of them do not have a complete
|
|
``MANIFEST.in`` file, so its possible that a tarball produced in that way will
|
|
be missing files.
|
|
|
|
.. _packaging-authors-changelog:
|
|
|
|
AUTHORS and ChangeLog
|
|
---------------------
|
|
|
|
*pbr* generates ``AUTHORS`` and ``ChangeLog`` files from *git* information.
|
|
This can cause problem in distro packaging if package maintainer is using *git*
|
|
repository for packaging source. If that is the case setting
|
|
``SKIP_GENERATE_AUTHORS``
|
|
|
|
::
|
|
|
|
export SKIP_GENERATE_AUTHORS=1
|
|
|
|
will cause logic around generating ``AUTHORS`` using *git* information to be
|
|
skipped. Similarly setting ``SKIP_WRITE_GIT_CHANGELOG``
|
|
|
|
::
|
|
|
|
export SKIP_WRITE_GIT_CHANGELOG=1
|
|
|
|
will cause logic around generating ``ChangeLog`` file using *git*
|
|
information to be skipped.
|
|
|
|
.. _packaging-releasenotes:
|
|
|
|
Release Notes
|
|
-------------
|
|
|
|
*pbr* generates a release notes file, typically called ``RELEASENOTES.rst``,
|
|
if `reno`_ is present and configured. You may wish to disable this
|
|
functionality. If that is the case setting ``SKIP_GENERATE_RENO``
|
|
|
|
::
|
|
|
|
export SKIP_GENERATE_RENO
|
|
|
|
will disable this feature.
|
|
|
|
.. _reno: https://docs.openstack.org/reno/latest/
|