Debian Codegraph @

doc/source/user/packagers.rst

raw
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/