5.10.2. Guidelines for porter uploads

If the package builds out of the box for the architecture to be ported to, you are in luck and your job is easy. This section applies to that case; it describes how to build and upload your binary package so that it is properly installed into the archive. If you do have to patch the package in order to get it to compile for the other architecture, you are actually doing a source NMU, so consult When and how to do an NMU instead.

For a porter upload, no changes are being made to the source. You do not need to touch any of the files in the source package. This includes debian/changelog.

The way to invoke dpkg-buildpackage is as dpkg-buildpackage -B -mporter-email. Of course, set porter-email to your email address. This will do a binary-only build of only the architecture-dependent portions of the package, using the binary-arch target in debian/rules.

If you are working on a Debian machine for your porting efforts and you need to sign your upload locally for its acceptance in the archive, you can run debsign on your .changes file to have it signed conveniently, or use the remote signing mode of dpkg-sig.

5.10.2.1. Recompilation or binary-only NMU

Sometimes the initial porter upload is problematic because the environment in which the package was built was not good enough (outdated or obsolete library, bad compiler, etc.). Then you may just need to recompile it in an updated environment. However, you have to bump the version number in this case, so that the old bad package can be replaced in the Debian archive (dak refuses to install new packages if they don’t have a version number greater than the currently available one).

You have to make sure that your binary-only NMU doesn’t render the package uninstallable. This could happen when a source package generates arch-dependent and arch-independent packages that have inter-dependencies generated using dpkg’s substitution variable $(Source-Version).

Despite the required modification of the changelog, these are called binary-only NMUs — there is no need in this case to trigger all other architectures to consider themselves out of date or requiring recompilation.

Such recompilations require special magic version numbering, so that the archive maintenance tools recognize that, even though there is a new Debian version, there is no corresponding source update. If you get this wrong, the archive maintainers will reject your upload (due to lack of corresponding source code).

The magic for a recompilation-only NMU is triggered by using a suffix appended to the package version number, following the form bnumber. For instance, if the latest version you are recompiling against was version 2.9-3, your binary-only NMU should carry a version of 2.9-3+b1. If the latest version was 3.4+b1 (i.e, a native package with a previous recompilation NMU), your binary-only NMU should have a version number of 3.4+b2. 2

Similar to initial porter uploads, the correct way of invoking dpkg-buildpackage is dpkg-buildpackage -B to only build the architecture-dependent parts of the package.

5.10.2.2. When to do a source NMU if you are a porter

Porters doing a source NMU generally follow the guidelines found in Non-Maintainer Uploads (NMUs), just like non-porters. However, it is expected that the wait cycle for a porter’s source NMU is smaller than for a non-porter, since porters have to cope with a large quantity of packages. Again, the situation varies depending on the distribution they are uploading to. It also varies whether the architecture is a candidate for inclusion into the next stable release; the release managers decide and announce which architectures are candidates.

If you are a porter doing an NMU for unstable, the above guidelines for porting should be followed, with two variations. Firstly, the acceptable waiting period — the time between when the bug is submitted to the BTS and when it is OK to do an NMU — is seven days for porters working on the unstable distribution. This period can be shortened if the problem is critical and imposes hardship on the porting effort, at the discretion of the porter group. (Remember, none of this is Policy, just mutually agreed upon guidelines.) For uploads to stable or testing, please coordinate with the appropriate release team first.

Secondly, porters doing source NMUs should make sure that the bug they submit to the BTS should be of severity serious or greater. This ensures that a single source package can be used to compile every supported Debian architecture by release time. It is very important that we have one version of the binary and source package for all architectures in order to comply with many licenses.

Porters should try to avoid patches which simply kludge around bugs in the current version of the compile environment, kernel, or libc. Sometimes such kludges can’t be helped. If you have to kludge around compiler bugs and the like, make sure you #ifdef your work properly; also, document your kludge so that people know to remove it once the external problems have been fixed.

Porters may also have an unofficial location where they can put the results of their work during the waiting period. This helps others running the port have the benefit of the porter’s work, even during the waiting period. Of course, such locations have no official blessing or status, so buyer beware.