+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 more difficult.
+ <p>
+The first and most important watchword is to respond quickly to bug 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).
+ <p>
+By far, most of the problems encountered by porters are caused by
+<em>packaging bugs</em> in the source packages. Here is a checklist
+of things you should check or be aware of.
+
+<enumlist>
+ <item>
+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 <url
+id="http://www.debian.org/doc/packaging-manuals/packaging.html/"
+name="Debian Packaging Manual">. Setting your architecture to ``i386''
+is usually incorrect.
+ <item>
+Make sure your source package is correct. Do <tt>dpkg-source -x
+<var>package</var>.dsc</tt> to make sure your source package unpacks
+properly. Then, in there, try building your package from scratch with
+<tt>dpkg-buildpackage</tt>.
+ <item>
+Make sure you don't ship your source package with the
+<file>debian/files</file> or <file>debian/substvars</file> files.
+They should be removed by the `clean' target of
+<file>debian/rules</file>.
+ <item>
+Make sure you don't rely on locally installed or hacked configurations
+or programs. For instance, you should never be calling programs in
+<file>/usr/local/bin</file> or the like. Try not to rely on programs
+be setup in a special way. Try building your package on another
+machine, even if it's the same architecture.
+ <item>
+Don't depend on the package your building already being installed (a
+sub-case of the above issue).
+ <item>
+Don't rely on <prgn>egcc</prgn> being available; don't rely on
+<prgn>gcc</prgn> being a certain version.
+ <item>
+Make sure your debian/rules contains separate ``binary-arch'' and
+``binary-indep'' targets, as the Debian Packaging 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 <tt>dpkg-buildpackage -b</tt>.
+ </enumlist>
+
+
+ <sect id="porter-guidelines">Guidelines for Porter Uploads
+ <p>
+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 NMU 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 <ref
+id="nmu-guidelines"> instead.
+ <p>
+In a binary NMU, no real changes are being made to the source. You do
+not need to touch any of the files in the source package. This
+includes <file>debian/changelog</file>.
+ <p>
+Sometimes you need to recompile a packages against other packages
+which have been updated, such as libraries. You do have to bump the
+version number in this case, so that the upgrade system can function
+properly. Even so, these are considered binary-only NMUs -- there is
+no need in this case for all architectures to recompile. You should
+set the version number as in the case of NMU versioning, but add a
+``.0.'' before the the NMU version. For instance, a recompile-only
+NMU of the source package ``foo_1.3-1'' would be numbered
+``foo_1.3-1.0.1''.
+ <p>
+The way to invoke <prgn>dpkg-buildpackage</prgn> is as
+<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course,
+set <var>porter-email</var> to your email address. This will do a
+binary-only build of only the architecture-dependant portions of the
+package, using the `binary-arch' target in <file>debian/rules</file>.
+
+
+ <sect1 id="source-nmu-when-porter">
+ <heading>When to do a source NMU if you are a porter</heading>
+ <p>
+Porters doing a source NMU generally follow the guidelines found in
+<ref id="nmu">, 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.
+ <p>
+Again, the situation varies depending on the distribution they are
+uploading to. Crucial fixes (i.e., changes need to get a source
+package to compile for a released-targeted architecture) can be
+uploaded with <em>no</em> waiting period for the `frozen' distribution.
+ <p>
+However, 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.)
+ <p>
+Secondly, porters doing source NMUs should make sure that the bug they
+submit to the BTS should be of severity `important' 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
+architecture in order to comply with many licenses.
+ <p>
+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
+compilers bugs and the like, make sure you <tt>#ifdef</tt> your work
+properly; also, document your kludge so that people know to remove it
+once the external problems have been fixed.
+ <p>
+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.
+
+
+ <sect>Tools for Porters
+ <p>
+There are several tools available for the porting effort. This section
+contains a brief introduction to these tools; see the package
+documentation or references for full information.
+
+
+ <sect1 id="quinn-diff">
+ <heading><package>quinn-diff</package>
+ <p>
+<package>quinn-diff</package> is used to locate the differences from
+one architecture to another. For instance, it could tell you which
+packages need to be ported for architecture <var>Y</var>, based on
+architecture <var>X</var>.
+
+
+ <sect1 id="buildd">
+ <heading><package>buildd</package>
+ <p>
+The <package>buildd</package> system is used as a distributed,
+client-server build distribution system. It is usually used in
+conjunction with <em>auto-builders</em>, which are ``slave'' hosts
+which simply check out and attempt to auto-build packages which need
+to be ported. There is also an email interface to the system, which
+allows porters to ``check out'' a source package (usually one which
+cannot yet be autobuilt) and work on it.
+ <p>
+<package>buildd</package> is not yet available as a package; however,
+most porting efforts are either using it currently or planning to use
+it in the near future. It collects a number of as yet unpackaged
+components which are currently very useful and in use continually,
+such as <prgn>andrea</prgn>, <prgn>sbuild</prgn> and
+<prgn>wanna-build</prgn>.
+ <p>
+Some of the data produced by <package>buildd</package> which is
+generally useful to porters is available on the web at <url
+id="&url-buildd;">. This data includes nightly updated information
+from <prgn>andrea</prgn> (source dependencies) and
+<package>quinn-diff</package> (packages needing recompilation).
+ <p>
+We are very excited about this system, since it potentially has so
+many uses. Independent development groups can use the system for
+different sub-flavors of Debian, which may or may not really be of
+general interest (for instance, a flavor of Debian built with gcc
+bounds checking). It will also enable Debian to recompile entire
+distributions quickly.
+
+
+ <sect1 id="dpkg-cross">
+ <heading><package>dpkg-cross</package>
+ <p>
+<package>dpkg-cross</package> is a tool for installing libraries and
+headers for cross-compiling in a way similar to
+<package>dpkg</package>. Furthermore, the functionality of
+<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is
+enhanced to support cross-compiling.
+
+
+
+
+ <chapt id="archive-manip">
+ <heading>Moving, Removing, Renaming, Adopting, and Orphaning
+ Packages</heading>
+ <p>
+Some archive manipulation operation are not automated in the Debian
+upload process. These procedures should be manually followed by
+maintainers. This chapter gives guidelines in what to do in these
+cases.
+
+ <sect>Moving packages
+ <p>
+Sometimes a package will change either its section. For instance, a
+package from the `non-free' section might be GPL'd in a later version,
+in which case, the package should be moved to `main' or
+`contrib'.<footnote> See the <url id="&url-debian-policy;"
+name="Debian Policy Manual"> for guidelines on what section a package
+belongs in.
+ </footnote>
+ <p>
+If you need to change the section for one of your packages, change the
+package control information to place the package in the desired
+section, and re-upload the package (see the <url id="&url-pkg-manual;"
+name="Debian Packaging Manual"> for details). Carefully examine the
+installation log sent to you when the package is installed into the
+archive. If for some reason the old location of the package remains,
+file a bug against <tt>ftp.debian.org</tt> asking that the old
+location be removed. Give details on what you did, since it might be
+a <prgn>dinstall</prgn> bug.
+ <p>
+If, on the other hand, you need to change the <em>subsection</em> of
+one of your packages (e.g., ``devel'', ``admin''), the procedure is
+slightly different. Correct the subsection as found in the control
+file of the package, and reupload that. Also, you'll need to update
+the override file, as described in <ref id="override-file">.
+
+
+ <sect id="removing-pkgs">Removing packages
+ <p>
+If for some reason you want to completely remove a package (say, if it
+is an old compatibility library which is not longer required), you
+need to file a bug against <tt>ftp.debian.org</tt> asking that the
+package be removed. Make sure you indicate which distribution the
+package should be removed from.
+ <p>
+If in doubt concerning whether a package is disposable, email
+&email-debian-devel; asking for opinions. Also of interest is the
+<prgn>apt-cache</prgn> program from the <package>apt</package>
+package. When invoked as <tt>apt-cache showpkg
+<var>package</var></tt>, the program will show details for
+<var>package</var>, including reverse depends.
+
+ <sect1>Removing packages from <tt>Incoming</tt>
+ <p>
+If you decide to remove a package from <tt>Incoming</tt>, it is nice
+but not required to send a notification of that to the appropriate
+announce list (either &email-debian-changes; or
+&email-debian-devel-changes;).
+
+ <sect>Replacing or renaming packages
+ <p>
+Sometimes you made a mistake naming the package and you need to rename
+it. In this case, you need to follow a two-step process. First, set
+your <file>debian/control</file> file to replace and conflict with the
+obsolete name of the package (see the <url id="&url-pkg-manual;"
+name="Debian Packaging Manual"> for details). Once you've uploaded
+that package, and the package has moved into the archive, file a bug
+against <tt>ftp.debian.org</tt> asking to remove the package with the
+obsolete name.
+
+ <sect id="orphaning">Orphaning a package
+ <p>
+If you can no longer maintain a package, you need to inform the others
+about that, and see that the package is marked as orphaned. Read
+instructions on the <url id="&url-wnpp;" name="WNPP web pages"> for more
+information.
+
+ <sect id="adopting">Adopting a package
+ <p>
+A list of packages in need of a new maintainer is available at in the
+<url name="Work-Needing and Prospective Packages list (WNPP)"
+id="&url-wnpp;">. If you wish to take over maintenance of any of the
+packages listed in the WNPP, please take a look at the aforementioned
+page for more information.
+ <p>
+It is not OK to simply take over a package that you feel is neglected
+-- that would be package hijacking. You can, of course, contact the
+current maintainer and ask them if you may take over the package.
+However, without their assent, you may not take over the package.
+Even if they ignore you, that is still not grounds to take over a
+package. If you really feel that a maintainer has gone AWOL (absent
+without leave), post a query to &email-debian-private;.