99 lines
3.7 KiB
ReStructuredText
99 lines
3.7 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`:
|
|
|
|
::
|
|
|
|
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 preleases 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.
|
|
|
|
Note: 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.
|
|
|
|
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`:
|
|
|
|
::
|
|
|
|
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.
|
|
|
|
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`
|
|
|
|
::
|
|
|
|
SKIP_GENERATE_AUTHORS=1
|
|
|
|
will cause logic around generating AUTHORS using git information to be
|
|
skipped. Similarly setting `SKIP_WRITE_GIT_CHANGELOG`
|
|
|
|
::
|
|
|
|
SKIP_WRITE_GIT_CHANGELOG=1
|
|
|
|
will cause logic around generating ChangeLog file using git
|
|
information to be skipped.
|