chiark / gitweb /
standardizing some of Raphael's entries
[developers-reference.git] / developers-reference.sgml
index cd78885b0e1b9888314fbaf39426cd898af8427b..6609c1b5a6dae6a18d164c395d515f93a6510390 100644 (file)
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.93 $">
+  <!entity cvs-rev "$Revision: 1.99 $">
   <!-- 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.
+The <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,54 @@ 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="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;
+    <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.
+
 
    <chapt id="pkgs">Managing Packages
        <p>
@@ -1033,17 +1077,14 @@ 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>
 If no original source is included in the upload, the original
 source tar-file used by <prgn>dpkg-source</prgn> when constructing the
 <tt>.dsc</tt> file and diff to be uploaded <em>must</em> be
-byte-for-byte identical with the one already in the archive.  If there
-is some reason why this is not the case, the new version of the
-original source should be uploaded, possibly by using the <tt>-sa</tt>
-flag.
+byte-for-byte identical with the one already in the archive.
 
 
        <sect2 id="upload-dist">Picking a distribution
@@ -1119,7 +1160,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>
@@ -1127,7 +1168,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
@@ -1159,7 +1200,7 @@ 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>.
@@ -1194,7 +1235,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>.
@@ -1258,7 +1299,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
@@ -1298,7 +1339,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
@@ -1310,10 +1351,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>
@@ -1374,10 +1411,10 @@ Under certain circumstances it is necessary for someone other than the
 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, do
-NMUs as part of their normal 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
+Debian porters, who compile packages for different architectures,
+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
 the freeze, or when the package maintainer is unable to release a fix
 in a timely fashion.
@@ -1401,8 +1438,7 @@ Source NMUs always involves changes to the source (even if it is just
 a change to <file>debian/changelog</file>).  This can be either a
 change to the upstream source, or a change to the Debian bits of the
 source.  Note, however, that source NMUs may also include
-architecture-dependent packages, as well as an updated Debian diff
-(or, more rarely, new upstream source as well).
+architecture-dependent packages, as well as an updated Debian diff.
        <p>
 A binary-only NMU is a recompilation and upload of a binary package
 for a given architecture.  As such, it is usually part of a porting
@@ -1536,12 +1572,6 @@ this, you'll have to invoke <prgn>dpkg-buildpackage</prgn> with the
 <tt>-sa</tt> switch to force the build system to pick up the new
 source package (normally it only looks for Debian revisions of '0' or
 '1' &mdash; it's not yet clever enough to know about `0.1').
-         <p>
-Remember, porters who are simply recompiling a package for a different
-architecture do not need to renumber.  Porters should use new version
-numbers if and only if they actually have to modify the source package
-in some way, i.e., if they are doing a source NMU and not a binary
-NMU.
 
 
        <sect2 id="nmu-changelog">
@@ -1566,16 +1596,12 @@ few changes to the package as possible, and they should always send a
 patch as a unified context diff (<tt>diff -u</tt>) detailing their
 changes to the Bug Tracking System.
          <p>
-What if you are simply recompiling the package?  In this case, the
-process is different for porters than it is for non-porters, as
-mentioned above.  If you are not a porter and are doing an NMU that
-simply requires a recompile (i.e., a new shared library is available
-to be linked against, a bug was fixed in
-<package>debhelper</package>), there must still be a changelog entry;
-therefore, there will be a patch.  If you are a porter, you are
-probably just doing a binary-only NMU.  (Note: this leaves out in the cold
-porters who have to do recompiles &mdash; chalk it up as a weakness in how
-we maintain our archive.)
+What if you are simply recompiling the package? If you just need to
+recompile it for a single architecture, then you may do a binary-only
+NMU as described in <ref id="binary-only-nmu"> which doesn't require any
+patch to be sent. If you want the package to be recompiled for all
+architectures, then you do a source NMU as usual and you will have to
+send a patch.
          <p>
 If the source NMU (non-maintainer upload) fixes some existing bugs,
 these bugs should be tagged <em>fixed</em> in the Bug Tracking
@@ -1592,13 +1618,14 @@ changes in the NMU are incorporated officially into the package by
 the official package maintainer.
          <p>
 Also, after doing an NMU, you have to open a new bug and include a
-patch showing all the changes you have made.  The normal maintainer
-will either apply the patch or employ an alternate method of fixing
-the problem.  Sometimes bugs are fixed independently upstream, which
-is another good reason to back out an NMU's patch.  If the maintainer
-decides not to apply the NMU's patch but to release a new version,
-the maintainer needs to ensure that the new upstream version really
-fixes each problem that was fixed in the non-maintainer release.
+patch showing all the changes you have made. Alternatively you can send
+that information to the existing bugs that are fixed by your NMU.
+The normal maintainer will either apply the patch or employ an alternate
+method of fixing the problem.  Sometimes bugs are fixed independently
+upstream, which is another good reason to back out an NMU's patch.
+If the maintainer decides not to apply the NMU's patch but to release a
+new version, the maintainer needs to ensure that the new upstream version
+really fixes each problem that was fixed in the non-maintainer release.
          <p>
 In addition, the normal maintainer should <em>always</em> retain the
 entry in the changelog file documenting the non-maintainer upload.
@@ -1609,8 +1636,7 @@ entry in the changelog file documenting the non-maintainer upload.
 Source NMU packages are built normally.  Pick a distribution using the
 same rules as found in <ref id="upload-dist">.  Just as described in
 <ref id="uploading">, a normal changes file, etc., will be built.  In
-fact, all the prescriptions from <ref id="upload"> apply, including
-the need to announce the NMU to the proper lists.
+fact, all the prescriptions from <ref id="upload"> apply.
          <p>
 Make sure you do <em>not</em> change the value of the maintainer in
 the <file>debian/control</file> file.  Your name as given in the NMU entry of
@@ -1633,7 +1659,7 @@ is different from the original architecture of the package
 maintainer's binary package.  It is a unique and essential activity.
 In fact, porters do most of the actual compiling of Debian packages.
 For instance, for a single <em>i386</em> binary package, there must be
-a recompile for each architecture, which is amounts to
+a recompile for each architecture, which amounts to
 &number-of-arches; more builds.
 
 
@@ -1664,7 +1690,7 @@ are set properly.  The best way to validate this is to use the
 <package>debootstrap</package> package to create an unstable chroot
 environment.  Within that chrooted environment, install the
 <package>build-essential</package> package and any package
-dependancies mention in <tt>Build-Depends</tt> and/or
+dependencies mention in <tt>Build-Depends</tt> and/or
 <tt>Build-Depends-Indep</tt>.  Finally, try building your package
 within that chrooted environment.
                <p>
@@ -1712,32 +1738,35 @@ try to run <tt>dpkg-buildpackage -b</tt>.
        <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-only NMU so
+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 <ref
 id="nmu-guidelines"> instead.
        <p>
-In a binary-only NMU, no real changes are being made to the source.  You do
+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 <file>debian/changelog</file>.
        <p>
 The way to invoke <prgn>dpkg-buildpackage</prgn> is as
-<tt>dpkg-buildpackage -B -e<var>porter-email</var></tt>.  Of course,
+<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="recompile-nmu-versioning">
-          <heading>Recompilation binary-only NMU versioning</heading>
+       <sect2 id="binary-only-nmu">
+          <heading>Recompilation or binary-only NMU</heading>
        <p>
-Sometimes you need to recompile a package against other packages which
-have been updated, such as libraries.  You do have to bump the version
-number in this case, so that the version comparison system can
-function properly.  Even so, these are considered binary-only NMUs
-&mdash; there is no need in this case to trigger all other
-architectures to consider themselves out of date or requiring
-recompilation.
+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, ...). Then you may just need to recompile it in
+an updated environment. However, you do have to bump the version number in
+this case, so that the old bad package can be replaced in the Debian archive
+(<prgn>katie</prgn> refuses to install new packages if they don't have a
+version number greater than the currently available one).  Despite the
+required modification of the changelog, these are called binary-only NMUs
+&mdash; there is no need in this case to trigger all other architectures
+to consider themselves out of date or requiring recompilation.
        <p>
 Such recompilations require special ``magic'' version numbering, so that
 the archive maintenance tools recognize that, even though there is a
@@ -1774,7 +1803,7 @@ 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 &mdash the time between when the
+Firstly, the acceptable waiting period &mdash; the time between when the
 bug is submitted to the BTS and when it is OK to do an NMU &mdash; is seven
 days for porters working on the unstable distribution.  This period
 can be shortened if the problem is critical and imposes hardship on
@@ -1884,27 +1913,37 @@ belongs in.
 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-debian-policy;"
-name="Debian Policy 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 bug in the archive maintenance software.
+name="Debian Policy Manual"> for details). If your new section is
+valid, it will be moved automatically. If it does not, then contact
+the ftpmasters in order to understand what happened.
        <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 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">.
 
 
       <sect1 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
+is an old compatibility library which is no 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.
+package should be removed from. Normally, you can only have packages
+removed from <em>unstable</em> and <em>experimental</em>.  Packages
+are not removed from <em>testing</em> directly. Rather, they will be
+removed automatically after the package has been removed from
+<em>unstable</em> and no package in <em>testing</em> depends on it.
+       <p>
+You also have to detail the reasons justifying that request. This is to
+avoid unwanted removals and to keep a trace of why a package has been
+removed. For example, you can provide the name of the package that
+supersedes the one to be removed.
+       <p>
+Usually you only ask the removal of a package maintained by yourself.
+If you want to remove another package, you have to get the approval
+of its last maintainer.
        <p>
 If in doubt concerning whether a package is disposable, email
 &email-debian-devel; asking for opinions.  Also of interest is the
@@ -1985,6 +2024,12 @@ 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>
@@ -2005,7 +2050,7 @@ 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.
 
       <sect1 id="bug-answering">Responding to bugs
@@ -2014,9 +2059,10 @@ 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>
@@ -2055,7 +2101,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
@@ -2064,8 +2110,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
@@ -2084,6 +2131,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>
@@ -2099,11 +2179,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.
@@ -2263,7 +2345,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>
@@ -2354,7 +2436,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.
@@ -2385,7 +2467,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>