5.10.1. Being kind to porters

Porters have a difficult and unique task, since they are required to deal with a large volume of packages. Ideally, every source package should build right out of the box. Unfortunately, this is often not the case. This section contains a checklist of gotchas often committed by Debian maintainers — common problems which often stymie porters, and make their jobs unnecessarily difficult.

The first and most important thing is to respond quickly to bugs or issues raised by porters. Please treat porters with courtesy, as if they were in fact co-maintainers of your package (which, in a way, they are). Please be tolerant of succinct or even unclear bug reports; do your best to hunt down whatever the problem is.

By far, most of the problems encountered by porters are caused by packaging bugs in the source packages. Here is a checklist of things you should check or be aware of.

1. Make sure that your Build-Depends and Build-Depends-Indep settings in debian/control are set properly. The best way to validate this is to use the debootstrap package to create an unstable chroot environment (see debootstrap). Within that chrooted environment, install the build-essential package and any package dependencies mentioned in Build-Depends and/or Build-Depends-Indep. Finally, try building your package within that chrooted environment. These steps can be automated by the use of the pbuilder program, which is provided by the package of the same name (see pbuilder).

   If you can’t set up a proper chroot, dpkg-depcheck may be of assistance (see dpkg-depcheck).

   See the Debian Policy Manual for instructions on setting build dependencies.

2. Don’t set architecture to a value other than all or any unless you really mean it. In too many cases, maintainers don’t follow the instructions in the Debian Policy Manual. Setting your architecture to only one architecture (such as i386 or amd64) is usually incorrect.

3. Make sure your source package is correct. Do dpkg-source -xpackage.dsc to make sure your source package unpacks properly. Then, in there, try building your package from scratch with dpkg-buildpackage.

4. Make sure you don’t ship your source package with the debian/files or debian/substvars files. They should be removed by the clean target of debian/rules.

5. Make sure you don’t rely on locally installed or hacked configurations or programs. For instance, you should never be calling programs in /usr/local/bin or the like. Try not to rely on programs being set up in a special way. Try building your package on another machine, even if it’s the same architecture.

6. Don’t depend on the package you’re building being installed already (a sub-case of the above issue). There are, of course, exceptions to this rule, but be aware that any case like this needs manual bootstrapping and cannot be done by automated package builders.

7. Don’t rely on the compiler being a certain version, if possible. If not, then make sure your build dependencies reflect the restrictions, although you are probably asking for trouble, since different architectures sometimes standardize on different compilers.

8. Make sure your debian/rules contains separate binary-arch and binary-indep targets, as the Debian Policy Manual requires. Make sure that both targets work independently, that is, that you can call the target without having called the other before. To test this, try to run dpkg-buildpackage -B.