diff options
Diffstat (limited to 'doc/source/packagers.rst')
| -rw-r--r-- | doc/source/packagers.rst | 39 |
1 files changed, 27 insertions, 12 deletions
diff --git a/doc/source/packagers.rst b/doc/source/packagers.rst index c799432..e135b57 100644 --- a/doc/source/packagers.rst +++ b/doc/source/packagers.rst @@ -1,6 +1,6 @@ -===================== - Notes for Packagers -===================== +=============================== + 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. @@ -12,10 +12,11 @@ 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 packager 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`: +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`: :: @@ -24,6 +25,20 @@ about whether its in its own git repo or not, you can set `PBR_VERSION`: 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 ============ @@ -43,10 +58,10 @@ Tarballs ======== `pbr` includes everything in a source tarball that is in the original `git` -repository. This can again cause havoc if a packager 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`: +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`: :: @@ -62,7 +77,7 @@ AUTHORS and ChangeLog ===================== `pbr` generates AUTHORS and ChangeLog files from git information. This -can cause problem in distro packaging if packager is using git +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` |