X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=6b29681fddae7aad3e5f9fc1c55476fd1681b83d;hb=9a31db3870ed2cfb0aa8983dab1e430f66aba09f;hp=061fe121fa434dabc573a46840fb3414f3169f5e;hpb=ae8f11eabe6095df197abdef31e8bbaab7125867;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 061fe12..6b29681 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.94 $">
+  <!entity cvs-rev "$Revision: 1.101 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -101,7 +101,7 @@ generally agreed-upon best practices.  Thus, it is what is called a
 So, you've read all the documentation, you've gone through the <url
 id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,
 understand what everything in the <package>hello</package> example
-package is for, and you're about to Debianize your favourite piece of
+package is for, and you're about to Debianize your favorite piece of
 software.  How do you actually become a Debian developer so that your
 work can be incorporated into the Project?
 	<p>
@@ -171,14 +171,14 @@ maintaining their own packages.  If you can help other maintainers by
 providing further information on a bug or even a patch, then do so!
 	<p>
 Registration requires that you are familiar with Debian's philosophy
-and technical documentation.  Furthermore, you need a GPG key which
-has been signed by an existing Debian maintainer.  If your GPG key
+and technical documentation.  Furthermore, you need a GnuPG key which
+has been signed by an existing Debian maintainer.  If your GnuPG key
 is not signed yet, you should try to meet a Debian maintainer in
 person to get your key signed.  There's a <url id="&url-gpg-coord;"
-name="GPG Key Signing Coordination page"> which should help you find
+name="GnuPG Key Signing Coordination page"> which should help you find
 a maintainer close to you (If you cannot find a Debian maintainer
 close to you, there's an alternative way to pass the ID check.  You
-can send in a photo ID signed with your GPG key.  Having your GPG
+can send in a photo ID signed with your GnuPG key.  Having your GnuPG
 key signed is the preferred way, however.  See the
 <url id="&url-newmaint-id;" name="identification page"> for more
 information about these two options.)
@@ -228,7 +228,7 @@ registered developer, an existing developer with whom you
 have worked over the past months has to express his belief that you
 can contribute to Debian successfully.
 	<p>
-When you have found an advocate, have your GPG key signed and have
+When you have found an advocate, have your GnuPG key signed and have
 already contributed to Debian for a while, you're ready to apply.
 You can simply register on our <url id="&url-newmaint-apply;"
 name="application page">.  After you have signed up, your advocate
@@ -259,8 +259,8 @@ In addition, if you have some packages ready for inclusion in Debian,
 but are waiting for your new maintainer application to go through, you
 might be able find a sponsor to upload your package for you.  Sponsors
 are people who are official Debian maintainers, and who are willing to
-criticize and upload your packages for you.  Sponsorees can request a
-sponsors at <url id="&url-sponsors;">.
+criticize and upload your packages for you.  Those who are seeking a
+sponsor can request one at <url id="&url-sponsors;">.
 	<p>
 If you wish to be a mentor and/or sponsor, more information is
 available in <ref id="newmaint">.
@@ -292,7 +292,7 @@ Read the documentation that comes with your software; read the <url
 id="&url-pgp-faq;" name="PGP FAQ">.
 	<p>
 If you add signatures to your public key, or add user identities, you
-can update the debian keyring by sending your key to the key server at
+can update the debian key ring by sending your key to the key server at
 <tt>&keyserver-host;</tt>.  If you need to add a completely new key,
 or remove an old key, send mail to &email-debian-keyring;.  The same
 key extraction routines discussed in <ref id="registering"> apply.
@@ -313,7 +313,7 @@ work for Debian and they can't be reached by email if any problem occurs.
 The other developers need to know that you're on vacation so that they'll
 do whatever is needed when such a problem occurs. Usually this means that
 other developers are allowed to NMU (see <ref id="nmu">) your package if a
-big problem (release critical bugs, security update, ...) occurs while
+big problem (release critical bugs, security update, etc.) occurs while
 you're on vacation.
 	<p>
 In order to inform the other developers, there's two things that you should do.
@@ -342,7 +342,7 @@ submit patches to fix upstream bugs, and you should evaluate and
 forward these patches upstream.
         <p>
 If you need to modify the upstream sources in order to build a policy
-conformant package, then you should propose a nice fix to the upstream
+compliant package, then you should propose a nice fix to the upstream
 developers which can be included there, so that you won't have to
 modify the sources of the next upstream version. Whatever changes you
 need, always try not to fork from the upstream sources.
@@ -533,7 +533,7 @@ Debian account should own the CVS root area, and why you need it.
 
       <sect1 id="devel-db">The Developers Database
 	<p>
-The Deverlopers Database, at <url id="&url-debian-db;">, is an LDAP
+The Developers Database, at <url id="&url-debian-db;">, is an LDAP
 directory for managing Debian developer attributes.  You can use this
 resource to search the list of Debian developers.  For information on
 keeping your entry the developer database up-to-date, see <ref
@@ -690,11 +690,11 @@ pages">.
 	<p>
 The sections <em>main</em>, <em>contrib</em>, and <em>non-free</em>
 are split into <em>subsections</em> to simplify the installation
-process and the maintainance of the archive.  Subsections are not
-formally defined, except perhaps the `base' subsection.
-Subsections simply exist to simplify the organization and browsing of
-available packages.  Please check the current Debian distribution to
-see which sections are available.
+process and the maintenance of the archive. Subsections simply exist to
+simplify the organization and browsing of available packages. The
+<url id="&url-debian-policy;" name="Debian Policy Manual"> gives
+the authoritative list of subsections.
+
 	<p>
 Note however that with the introduction of package pools (see the top-level
 <em>pool/</em> directory), the subsections in the form of subdirectories
@@ -760,15 +760,11 @@ distribution change from day-to-day. Since no special effort is done
 to make sure everything in this distribution is working properly, it is
 sometimes literally unstable.
 	<p>
-Packages get copied from <em>unstable</em> to <em>testing</em> if they
-satisfy certain criteria. To get into <em>testing</em> distribution, a
-package needs to be in the archive for two weeks and not have any
-release critical bugs. After that period, it will propagate into
-<em>testing</em> as soon as anything it depends on is also added. This
-process is automatic.  You can see some notes on this system as well
-as <tt>update_excuses</tt> (describing which packages are valid
-candidates, which are not, and why not) at <url
-id="&url-testing-maint;">.
+The testing distribution is generated automatically by taking
+packages from unstable if they satisfy certain criteria. Those
+criteria should ensure a good quality for packages within testing.
+<ref id="testing-scripts"> are launched each day after the
+new packages have been installed.
 	<p>
 After a period of development, once the release manager deems fit, the
 <em>testing</em> distribution is frozen, meaning that the policies
@@ -879,6 +875,171 @@ real distribution directories use the <em>code names</em>, while
 symbolic links for <em>stable</em>, <em>testing</em>, and
 <em>unstable</em> point to the appropriate release directories.
 
+    <sect id="incoming-system">
+	<heading>The Incoming system
+	<p>
+The Incoming system is responsible of collecting updated packages and
+installing them in the Debian archive. It consists of a set of
+directories and scripts that are installed both on <tt>&ftp-master-host;</tt>
+and <tt>&non-us-host;</tt>.
+	<p>
+Packages are uploaded by all the maintainers into an <tt>unchecked</tt>
+directory. This directory is scanned every 15 minutes by the katie script
+that verifies the integrity of the package and the cryptographic
+signature.  If the package is considered ready to be installed, it
+is moved into an <tt>accepted</tt> directory. If it is the first upload of
+the package then it is moved in a <tt>new</tt> directory waiting an
+approval of the ftpmasters. If the package contains files to be installed
+"by-hand" is is moved in the <tt>byhand</tt> directory waiting a manual
+installation by the ftpmasters. Otherwise, if any error has been detected,
+the package is refused and is moved in the <tt>reject</tt> directory.
+	<p>
+Once the package is accepted the system sends a confirmation
+mail to the maintainer, closes all the bugs marked as fixed by the upload
+and the autobuilders may start recompiling it. The package is now publicly
+accessible at <url id="&url-incoming;"> (there is no
+such URL for packages in the non-US archive) until it is really installed
+in the Debian archive. This happens only once a day, the package
+is then removed from incoming and installed in the pool along with all
+the other packages. Once all the other updates (generating new
+<tt>Packages</tt> and <tt>Sources</tt> files for example) have been made,
+a special script is called to ask all the primary mirrors to update
+themselves.
+	<p>
+All debian developers have write access to the <tt>unchecked</tt>
+directory in order to upload their packages, they also have that access
+to the <tt>reject</tt> directory in order to remove their bad uploads
+or to move some files back in the <tt>unchecked</tt> directory. But
+all the other directories are only writable by the ftpmasters, that is
+why you can not remove your upload once it has been accepted.
+	<p>
+The <tt>unchecked</tt> directory has a special <tt>DELAYED</tt>
+subdirectory. It is itself subdivised in nine directories
+called <tt>1-day</tt> to <tt>9-day</tt>. Packages which are uploaded in
+one of those directories will be moved in the real unchecked
+directory after the corresponding number of days.
+This is done by a script that is run each day and which moves the
+packages between the directories. Those which are in "1-day" are
+installed in <tt>unchecked</tt> while the others are moved in the 
+adjacent directory (for example, a package in <tt>5-day</tt> will
+be moved in <tt>4-day</tt>). This feature is particularly useful
+for people who are doing non-maintainer uploads. Instead of
+waiting before uploading a NMU, it is uploaded as soon as it is
+ready but in one of those <tt>DELAYED/x-day</tt> directories.
+That leaves the corresponding number of days to the maintainer
+in order to react and upload himself another fix if he is not
+completely satisfied with the NMU. Alternatively he can remove
+the NMU by himself.
+	<p>
+The use of that delayed feature can be simplified with a bit
+of integration with your upload tool, the following addition to 
+the <prgn>dupload</prgn> configuration file should be
+considered. 
+	<p>
+<example>
+$delay = ($ENV{DELAY} || 7);
+$cfg{'delayed'} = {
+         fqdn => "ftp-master.debian.org",
+         login => "yourdebianlogin",
+         incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",
+         visibleuser => "yourdebianlogin",
+         visiblename => "debian.org",
+         fullname => "Your Full Name",
+         dinstall_runs => 1,
+         method => "scpb"
+};
+</example>
+	<p>
+<prgn>dupload</prgn> can now be used to easily upload a package
+in one of the delayed directories :
+<example>DELAY=5 dupload --to delayed &lt;changes-file&gt;</example>
+
+    <sect id="testing-scripts">
+	<heading>The testing scripts</heading>
+	<p>
+The testing scripts are run each day after the installation of the
+updated packages. They generate the <file>Packages</file> files for
+the <em>testing</em> distribution, but they do so in an intelligent manner
+trying to avoid any inconsistency and trying to use only
+non-buggy packages.
+	<p>The inclusion of a package from <em>unstable</em> is conditionned:
+<list>
+    <item>
+The package must have been available in <em>unstable</em> for several days;
+the precise number depends on the urgency field's value of the upload. It
+is 10 days for low urgency, 5 days for medium urgency and 2 days for high
+urgency. Those delays may be doubled during a freeze;
+    <item>
+It must have less release-critical bugs than the version available
+in <em>testing</em>;
+    <item>
+It must be available on all architectures on which it has been
+previously built. <ref id="madison"> may be of interest to
+check that information;
+    <item>
+It must not break any dependency of a package that is already available
+in <em>testing</em>;
+    <item>
+The packages on which it depends must either be available in <em>testing</em>
+or they must be accepted into <em>testing</em> at the same time (and they will
+if they respect themselves all the criteria);
+</list>
+	<p>
+The scripts are generating some output files to explain why some packages
+are kept out of testing. They are available at <url
+id="&url-testing-maint;">. Alternatively, it is possible to use
+the <prgn>grep-excuses</prgn> program part of the
+<package>devscripts</package> package. It can be easily put in a crontab
+to keep someone informed of the progression of his packages in testing.
+	<p>
+The <tt>update_excuses</tt> file does not always give the precise reason
+why the package is refused, one may have to find it by himself by looking
+what would break with the inclusion of the package. The <url
+id="&url-testing-faq;" name="testing FAQ"> gives some more information
+about the usual problems which may be causing such troubles.
+	<p>
+Sometimes, some packages never enter testing because the set of
+inter-relationship is too complicated and can not be sorted out
+by the scripts. In that case, the release manager must be
+contacted, and he will force the inclusion of the packages.
+
+    <sect id="pkg-info">Package's information
+	<p>
+
+      <sect1 id="pkg-info-web">On the web
+	<p>
+Each package has several dedicated web pages that contains many
+informations. First <tt>http://&packages-host;/&lt;package&gt;</tt>
+will let you discover a presentation of each version of the package
+available in the various distributions. It includes its description,
+the dependencies and some links to download the package.
+	<p>
+The bug tracking system sorts the bugs by package, you can
+watch the bugs of each package at
+<tt>http://&bugs-host;/&lt;package&gt;</tt>.
+
+      <sect1 id="madison">The madison utility
+        <p>
+<prgn>madison</prgn> is a command-line utility that is available
+on both <tt>&ftp-master-host;</tt> and <tt>&non-us-host;</tt>. It
+uses a single argument corresponding to a package name. In result
+it displays which version of the package is available for each
+architecture and distribution combination. An example will explain
+it better.
+	<p>
+<example>
+$ madison libdbd-mysql-perl
+libdbd-mysql-perl |   1.2202-4 |        stable | source, alpha, arm, i386, m68k, powerpc, sparc
+libdbd-mysql-perl |   1.2216-2 |       testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+libdbd-mysql-perl | 1.2216-2.0.1 |       testing | alpha
+libdbd-mysql-perl |   1.2219-1 |      unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc
+</example>
+	<p>
+In this example, you can see that the version in unstable differs from
+the version in testing and that there has been a binary-only NMU of the
+package for the alpha architecture. Each time the package has been
+recompiled on most of the architectures.
+
 
    <chapt id="pkgs">Managing Packages
 	<p>
@@ -1033,7 +1194,7 @@ files, and will not need to be re-uploaded.
 By default, <prgn>dpkg-genchanges</prgn> and
 <prgn>dpkg-buildpackage</prgn> will include the original source tar
 file if and only if the Debian revision part of the source version
-number is 0 or 1, indicating a new upstream version.  This behaviour
+number is 0 or 1, indicating a new upstream version.  This behavior
 may be modified by using <tt>-sa</tt> to always include it or
 <tt>-sd</tt> to always leave it out.
 	  <p>
@@ -1116,7 +1277,7 @@ Extra care should be taken when uploading to <em>stable</em>. Basically, a
 package should only be uploaded to stable if one of the following happens:
 <list>
 	<item>a security problem (e.g. a Debian security advisory)
-	<item>a truely critical functionality problem
+	<item>a truly critical functionality problem
 	<item>the package becomes uninstallable
 	<item>a released architecture lacks the package
 </list>
@@ -1124,7 +1285,7 @@ package should only be uploaded to stable if one of the following happens:
 It is discouraged to change anything else in the package that isn't
 important, because even trivial fixes can cause bugs later on. Uploading
 new upstream versions to fix security problems is deprecated; applying the
-specific patch from the new upstream version to the old one ("backporting"
+specific patch from the new upstream version to the old one ("back-porting"
 the patch) is the right thing to do in most cases.
 	    <p>
 Packages uploaded to <em>stable</em> need to be compiled on systems running
@@ -1156,21 +1317,23 @@ if you use anonymous FTP to upload, place them into
 <ftppath>/pub/UploadQueue/</ftppath>.  Please note that you should transfer
 the changes file last.  Otherwise, your upload may be rejected because the
 archive maintenance software will parse the changes file and see that not
-all files have been uploaded.  If you don't want to bother with transfering
+all files have been uploaded.  If you don't want to bother with transferring
 the changes file last, you can simply copy your files to a temporary
 directory on <tt>ftp-master</tt> and then move them to
 <tt>&us-upload-dir;</tt>.
           <p>
-<em>Note:</em> Do not upload to <tt>ftp-master</tt> packages
-containing software that is patent-restricted by the United States
-government, nor any cryptographic packages which belong to
-<em>contrib</em> or <em>non-free</em>.  If you can't upload it to
-<tt>ftp-master</tt>, then neither can you upload it to the overseas
-upload queues on <tt>chiark</tt> or <tt>erlangen</tt>.  Uploads of
+<em>Note:</em> Do not upload to <tt>ftp-master</tt> cryptographic
+packages which belong to <em>contrib</em> or <em>non-free</em>. Uploads of
 such software should go to <tt>non-us</tt> (see <ref
-id="upload-non-us">).  If you are not sure whether U.S. patent
-controls or cryptographic controls apply to your package, post a
-message to &email-debian-devel; and ask.
+id="upload-non-us">). Furthermore packages containing code that is
+patent-restricted by the United States government can not be uploaded to
+<tt>ftp-master</tt>; depending on the case they may still be uploaded to
+<tt>non-US/non-free</tt> (it's in non-free because of distribution issues
+and not because of the license of the software). If you can't upload it to
+<tt>ftp-master</tt>, then neither can you upload it to the overseas upload
+queues on <tt>chiark</tt> or <tt>erlangen</tt>. If you are not sure
+whether U.S. patent controls or cryptographic controls apply to your
+package, post a message to &email-debian-devel; and ask.
 	  <p>
 You may also find the Debian packages <package>dupload</package> or
 <package>dput</package> useful
@@ -1191,7 +1354,7 @@ As discussed above, export controlled software should not be uploaded
 to <tt>ftp-master</tt>.  Instead, upload the package to
 <ftpsite>non-us.debian.org</ftpsite>, placing the files in
 <tt>&non-us-upload-dir;</tt> (both <ref id="dupload"> and <ref
-id="dput"> can be used also, with the right invokation). By default,
+id="dput"> can be used also, with the right invocation). By default,
 you can use the same account/password that works on
 <tt>ftp-master</tt>.  If you use anonymous FTP to upload, place the
 files into <ftppath>/pub/UploadQueue/</ftppath>.
@@ -1255,7 +1418,7 @@ The upload must be a complete Debian upload, as you would put it into
 <tt>ftp-master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
 along with the other files mentioned in the <tt>.changes</tt>. The
 queue daemon also checks that the <tt>.changes</tt> is correctly
-PGP-signed by a Debian developer, so that no bogus files can find
+signed with GnuPG or OpenPGP by a Debian developer, so that no bogus files can find
 their way to <tt>ftp-master</tt> via this queue. Please also make sure that
 the <tt>Maintainer</tt> field in the <tt>.changes</tt> contains
 <em>your</em> e-mail address. The address found there is used for all
@@ -1295,7 +1458,7 @@ When a package is uploaded, an announcement should be posted to one of
 the ``debian-changes'' lists. This is now done automatically by the archive
 maintenance software when it runs (usually once a day). You just need to use
 a recent <package>dpkg-dev</package> (&gt;= 1.4.1.2). The mail generated by
-the archive maintenance software will contain the PGP/GPG signed 
+the archive maintenance software will contain the OpenPGP/GnuPG signed 
 <tt>.changes</tt> files that you uploaded with your package.
 Previously, <prgn>dupload</prgn> used to send those announcements, so
 please make sure that you configured your <prgn>dupload</prgn> not to
@@ -1307,10 +1470,6 @@ If a package is released with the <tt>Distribution:</tt> set to
 package is released with <tt>Distribution:</tt> set to `unstable',
 or `experimental', the announcement will be
 posted to &email-debian-devel-changes; instead.
-	<p>
-The <prgn>dupload</prgn> program is clever enough to determine
-where the announcement should go, and will automatically mail the
-announcement to the right list.  See <ref id="dupload">.
 
       <sect1 id="upload-notification">
 	<heading>Notification that a new package has been installed</heading>
@@ -1372,7 +1531,7 @@ official package maintainer to make a release of a package.  This is
 called a non-maintainer upload, or NMU.
        <p>
 Debian porters, who compile packages for different architectures,
-occasionnaly do binary-only NMUs as part of their porting activity
+occasionally do binary-only NMUs as part of their porting activity
 (see <ref id="porting">).  Another reason why NMUs are done is when a
 Debian developers needs to fix another developers' packages in order to
 address serious security problems or crippling bugs, especially during
@@ -1711,7 +1870,7 @@ includes <file>debian/changelog</file>.
 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
+binary-only build of only the architecture-dependent portions of the
 package, using the `binary-arch' target in <file>debian/rules</file>.
 
 	<sect2 id="binary-only-nmu">
@@ -1880,7 +2039,7 @@ the ftpmasters in order to understand what happened.
 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 get the
+file of the package, and re-upload that.  Also, you'll need to get the
 override file updated, as described in <ref id="override-file">.
 
 
@@ -1911,6 +2070,12 @@ If in doubt concerning whether a package is disposable, email
 package.  When invoked as <tt>apt-cache showpkg
 <var>package</var></tt>, the program will show details for
 <var>package</var>, including reverse depends.
+	<p>
+Once the package has been removed, the package's bugs should be handled.
+They should either be reassigned to another package in the case where
+the actual code has evolved into another package (e.g. <tt>libfoo12</tt>
+was removed because <tt>libfoo13</tt> supersedes it) or closed if the
+software is simply no more part of Debian.
 
 	<sect2>Removing packages from <tt>Incoming</tt>
 	  <p>
@@ -1932,7 +2097,8 @@ obsolete name of the package (see the <url id="&url-debian-policy;"
 name="Debian Policy 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.
+obsolete name. Do not forget to properly reassign the package's bugs
+at the same time.
 
       <sect1 id="orphaning">Orphaning a package
 	<p>
@@ -1984,12 +2150,20 @@ right away.
 
 
     <sect id="bug-handling">Handling package bugs
+	<p>
+Often as a package maintainer, you find bugs in other packages or else
+have bugs reported to your packages which need to be reassigned.  The
+<url id="&url-bts-control;" name="BTS instructions"> can tell you how
+to do this.  Some information on filing bugs can be found in <ref
+id="submit-bug">.
 
       <sect1>Monitoring bugs
 	<p>
 If you want to be a good maintainer, you should periodically check the
 <url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your
 packages.  The BTS contains all the open bugs against your packages.
+You can check them by browsing this page:
+<tt>http://&bugs-host;/yourlogin@debian.org</tt>.
 	<p>
 Maintainers interact with the BTS via email addresses at
 <tt>bugs.debian.org</tt>.  Documentation on available commands can be
@@ -2004,38 +2178,19 @@ outlining all the open bugs against your packages:
 # ask for weekly reports of bugs in my packages
 &cron-bug-report;
 </example>
-Replace <var>address</var> with you official Debian
+Replace <var>address</var> with your official Debian
 maintainer address.
 
-      <sect id="submit-bug">Submitting bugs
-	<p>
-Often as a package maintainer, you find bugs in other packages or else
-have bugs reported to your packages which need to be reassigned.  The
-<url id="&url-bts-control;" name="BTS instructions"> can tell you how
-to do this.
-	<p>
-We encourage you to file bugs when there are problems.  Try to submit
-the bug from a normal user account at which you are likely to receive
-mail.  Do not submit bugs as root.
-	<p>
-Make sure the bug is not already filed against a package.  Try to do a
-good job reporting a bug and redirecting it to the proper location.
-For extra credit, you can go through other packages, merging bugs
-which are reported more than once, or setting bug severities to
-`fixed' when they have already been fixed.  Note that when you are
-neither the bug submitter nor the package maintainer, you should
-not actually close the bug (unless you secure permission from the
-maintainer).
-
       <sect1 id="bug-answering">Responding to bugs
 	<p>
 Make sure that any discussions you have about bugs are sent both to
 the original submitter of the bug, and the bug itself (e.g.,
 <email>123@bugs.debian.org</email>).
 	<p>
-You should <em>never</em> close bugs via the bug server `close'
+You should <em>never</em> close bugs via the bug server <tt>close</tt>
 command sent to &email-bts-control;.  If you do so, the original
-submitter will not receive any feedback on why the bug was closed.
+submitter will not receive any information about why the bug was
+closed.
 
       <sect1 id="bug-housekeeping">Bug housekeeping
 	<p>
@@ -2074,7 +2229,7 @@ acme-cannon (3.1415) unstable; urgency=low
   * Frobbed with options (closes: Bug#98339)
   * Added safety to prevent operator dismemberment, closes: bug#98765,
     bug#98713, #98714.
-  * Added manpage. Closes: #98725.
+  * Added man page. Closes: #98725.
 </example>
 
 Technically speaking, the following Perl regular expression is what is
@@ -2083,8 +2238,9 @@ used:
   /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
 </example>
 
-The author prefers the <tt>(closes: Bug#<var>XXX</var>)</tt> syntax,
-since it stands out from the rest of the changelog entries.
+The author prefers the <tt>closes: #<var>XXX</var>)</tt> syntax, as
+one of the most concise and easiest to integrate with the text of the
+<file>changelog</file>.
 	<p>
 If you want to close bugs the old fashioned, manual way, it is usually
 sufficient to mail the <tt>.changes</tt> file to
@@ -2103,6 +2259,39 @@ latest version of the distribution (usually from 'unstable') using the
 latest <package>lintian</package>.
 
 
+  <chapt id="best-pkging-practices">
+    <heading>Best Packaging Practices</heading>
+    <p>
+Debian's quality is largely due to its Policy that all packages
+follow. But it's also because we accumulated years of experience
+in packaging; very talented people created great tools to make
+good packages without much troubles.
+    <p>
+This chapter provides the best known solutions to common problems
+faced during packaging. It also lists various advice collected on
+several mailing lists. By following them, you will make Debian's quality
+even better.
+
+    <sect id="misc-advice">
+	<heading>Miscellaenous advice</heading>
+
+	<sect1 id="writing-desc">
+	    <heading>Writing useful descriptions</heading>
+	    <p>
+The description of the package (as defined by the corresponding field
+in the <file>control</file> file) is usually the first information
+available to the user before he installs it. As such, it should
+provide all the required information to let him decide whether
+to install the package.
+	    <p>
+For example, apart from the usual description that you adapt from the
+upstream <file>README</file>, you should include the URL of the
+website if there's any. If the package is not yet considered stable
+by the author, you may also want to warn the user that the
+package is not ready for production use.
+
+
+
   <chapt id="beyond-pkging">
     <heading>Beyond Packaging</heading>
     <p>
@@ -2118,11 +2307,13 @@ the most critical thing to spend their time on.
     <sect id="submit-bug">
         <heading>Bug Reporting</heading>
         <p>
-We encourage you to file bugs as you find them in Debian packages.
+We encourage you to file bugs as you find them in Debian packages.  In
+fact, Debian developers are often the first line testers.  Finding and
+reporting bugs in other developer's packages improves the quality of
+Debian.
 	<p>
-Try to submit
-the bug from a normal user account at which you are likely to receive
-mail.  Do not submit bugs as root.
+Try to submit the bug from a normal user account at which you are
+likely to receive mail.  Do not submit bugs as root.
 	<p>
 Make sure the bug is not already filed against a package.  Try to do a
 good job reporting a bug and redirecting it to the proper location.
@@ -2132,6 +2323,12 @@ which are reported more than once, or setting bug severities to
 neither the bug submitter nor the package maintainer, you should
 not actually close the bug (unless you secure permission from the
 maintainer).
+	<p>
+From time to time you may want to check what has been going on
+with the bug reports that you submitted. Take this opportunity to
+close those that you can't reproduce anymore. To find
+out all the bugs you submitted, you just have to visit
+<tt>http://&bugs-host;/your-email@your-isp.com</tt>.
 
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
 	<p>
@@ -2183,13 +2380,29 @@ he maintains and any Release Critical bugs filled against them.
 Send all this information to &email-debian-qa;, in order to let the 
 QA people do whatever is needed.
 
-
+    <sect id="contacting-maintainers">Contacting other maintainers
+      <p>
+During your lifetime within Debian, you will have to contact other
+maintainers for various reasons. You may want to discuss a new
+way of cooperating between a set of related packages, or you may
+simply remind someone that a new upstream version is available
+and that you need it.
+      <p>
+Whatever the reason, it is a pain to lookup the email address of the
+maintainer of the package that you are interested in. Fortunately, you
+can use a simple email alias : <tt>&lt;package&gt;@&packages-host;</tt>.
+<tt>&lt;package&gt;</tt> can be the name of a source or a binary package.
+      <p>
+You may also be interested by contacting the persons who are
+subscribed to a given source package via the Package Tracking
+System. You can do so by using the <tt>&lt;package&gt;@&pts-host;</tt>
+address.
 
 
     <sect id="newmaint">
       <heading>Interacting with prospective Debian developers</heading>
       <p>
-Debian's success depends on it's ability to attract and retain new and
+Debian's success depends on its ability to attract and retain new and
 talented volunteers.  If you are an experienced developer, we
 recommend that you get involved with the process of bringing in new
 developers.  This section describes how to help new prospective
@@ -2282,7 +2495,7 @@ id="upload-checking"> and <ref id="lintian-reports">.
         <p>
 <package>debconf</package> provides a consistent interface to
 configuring packages interactively.  It is user interface
-independant, allowing end-users to configure packages with a
+independent, allowing end-users to configure packages with a
 text-only interface, an HTML interface, or a dialog interface.  New
 interfaces can be added modularly.
         <p>
@@ -2373,7 +2586,7 @@ a version control system.
       <sect id="dupload">
 	<heading><package>dupload</package>
 	<p>
-<package>dupload</package> is a package and a script to automagically
+<package>dupload</package> is a package and a script to automatically
 upload Debian packages to the Debian archive, to log the upload, and
 to send mail about the upload of a package.  You can configure it for
 new upload locations or methods.
@@ -2404,7 +2617,7 @@ user: <tt>dpkg-buildpackage -rfakeroot</tt>.
 	<heading><package>debootstrap</package>
 	<p>
 The <package>debootstrap</package> package and script allows you to
-"bootstrap" a Debian base system into any part of your filesystem.
+"bootstrap" a Debian base system into any part of your file-system.
 By "base system", we mean the bare minimum of packages required to
 operate and install the rest of the system.
 	<p>