comments requested on new porter section of devel-ref

[Adam Di Carlo <adam@onshore.com>]

Below is a snippet of the front part of a new chapter in the
developer's reference featuring porters.  Much of the rest of the
chapter comes together form other parts of the document.

Note this is not yet committed to CVS even, and fresh written tonight.


Comments requested.

Changelog entry:

  * Ch. "Porting and Being Ported": porter information broken out into it's
    own chapter, Sec. "Guidelines for Porter Uploads" and "When to do a
    source NMU if you are a porter" moved to this chapter; porter tool
    descriptions such as 'quinn-diff' moved to this section.  Sec. "Being
    Kind to Porters" added.


--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>

7. Porting and Being Ported 
----------------------------

     Debian supports an ever-increasing number of architectures. Even if
     you are not a porter, and you don't use any architecture but one, it
     is part of your duty as a maintainer to be aware of issues of
     portability. Therefore, even if you are not a porter, you should read
     most of this chapter.

     Porting is the act of building Debian packages for architectures which
     is different from the original architecture of the package
     maintainer's binary package. It is a unique and essential activity. In
     fact, porters who do most of the actual compiling of Debian packages.
     For instance, for one _x86_ binary package, there has to be a
     recompile for each architecture, which is around five more builds.


7.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 more difficult.

     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).
     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.   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 Packaging Manual
          (http://www.debian.org/doc/packaging-manuals/packaging.html/).
          Setting your achitecture to ``x86'' is usually incorrect.

     2.   Make sure your source package is correct. Do `dpkg-source -x
          <package>.dsc' to make sure your source package unpacks properly.
          Then, in there, try building your package from scratch with
          `dpkg-buildpackage'.

     3.   Make sure you don't ship your binary package with the
          `debian/file' file.

     4.   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 be setup in a special way. Try building your package
          on another machine, even if it's the same architecture.