spell checking, tag fixes, editorial review -- no new content

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 22d739df3d06b48bdbdf05b3411c45e5c535e45f..2ed1d7f1d6ac2e4b36945bfeab10e02e4ccabad1 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->

-  <!entity cvs-rev "$Revision: 1.130 $">
+  <!entity cvs-rev "$Revision: 1.131 $">

   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--


@@ -538,7 +538,7 @@ as long as the developers follow the rules set forth in the
 Generally speaking, you can use these machines for Debian-related purposes
 as you see fit.  Please be kind to system administrators, and do not use
 up tons and tons of disk space, network bandwidth, or CPU without first
 Generally speaking, you can use these machines for Debian-related purposes
 as you see fit.  Please be kind to system administrators, and do not use
 up tons and tons of disk space, network bandwidth, or CPU without first

-getting the approval of the admins.  Usually these machines are run by
+getting the approval of the system administrators.  Usually these machines are run by

 volunteers.
        <p>
 Please take care to protect your Debian passwords and SSH keys installed on
 volunteers.
        <p>
 Please take care to protect your Debian passwords and SSH keys installed on


@@ -664,7 +664,7 @@ the finger service on Debian servers, try
 This database lets you register some other information like public SSH
 keys that will be automatically installed on the official debian machines
 or like *.debian.net DNS entry. Those features are documented
 This database lets you register some other information like public SSH
 keys that will be automatically installed on the official debian machines
 or like *.debian.net DNS entry. Those features are documented

-here : <url id="&url-debian-db-mail-gw;">
+at <url id="&url-debian-db-mail-gw;">.

 
     <sect id="servers-mirrors">Mirrors of Debian servers
        <p>
 
     <sect id="servers-mirrors">Mirrors of Debian servers
        <p>


@@ -999,13 +999,13 @@ 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 a directory called
 and <tt>&non-us-host;</tt>.
        <p>
 Packages are uploaded by all the maintainers into a directory called

-<file>unchecked</file>. This directory is scanned every 15 minutes by the katie script
-that verifies the integrity of the uploaded packages and the cryptographic
+<file>unchecked</file>. This directory is scanned every 15 minutes by
+the <prgn>katie</prgn> script, which verifies the integrity of the uploaded packages and the cryptographic

 signatures.  If the package is considered ready to be installed, it
 is moved into the <file>accepted</file> directory. If this is the first upload of
 the package, it is moved in the <file>new</file> directory, where it waits
 for an approval of the ftpmasters. If the package contains files to be installed
 signatures.  If the package is considered ready to be installed, it
 is moved into the <file>accepted</file> directory. If this is the first upload of
 the package, it is moved in the <file>new</file> directory, where it waits
 for an approval of the ftpmasters. If the package contains files to be installed

-"by-hand" is is moved in the <file>byhand</file> directory, where it waits
+"by-hand" it is moved in the <file>byhand</file> directory, where it waits

 for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
 the package is refused and is moved in the <file>reject</file> directory.
        <p>
 for a manual installation by the ftpmasters. Otherwise, if any error has been detected,
 the package is refused and is moved in the <file>reject</file> directory.
        <p>


@@ -1116,20 +1116,20 @@ 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.
 
 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
+    <sect id="pkg-info">Package information

        <p>
 
       <sect1 id="pkg-info-web">On the web
        <p>
        <p>
 
       <sect1 id="pkg-info-web">On the web
        <p>

-Each package has several dedicated web pages that contain a lot of
-information. <tt>http://&packages-host;/<var>package-name</var></tt>
-will display each version of the package
-available in the various distributions.  The per-version detailed
-information includes the package description,
-the dependencies and links to download the package.
+Each package has several dedicated web pages.
+<tt>http://&packages-host;/<var>package-name</var></tt>
+displays each version of the package
+available in the various distributions.  Each version links to a page
+which provides information, including the package description,
+the dependencies and package download links.

        <p>
        <p>

-The bug tracking system sorts the bugs by package, you can
-watch the bugs of each package at
+The bug tracking system track bugs for each package.  You can
+view the bugs of a given package at the URL

 <tt>http://&bugs-host;/<var>package-name</var></tt>.
 
       <sect1 id="madison">The <prgn>madison</prgn> utility
 <tt>http://&bugs-host;/<var>package-name</var></tt>.
 
       <sect1 id="madison">The <prgn>madison</prgn> utility


@@ -1309,18 +1309,17 @@ accepts the <em>cvs</em> keyword will receive the notifications.
 
     <sect id="ddpo">Developer's packages overview
        <p>
 
     <sect id="ddpo">Developer's packages overview
        <p>

-This is a nice web portal that displays a table of all the packages
-of a single developer (including those where he's listed as
-co-maintainer). The table gives a good summary about his
-packages : number of bugs by severity, list of available versions in each
-distributon, testing status and much more including links to any other
+A QA (quality assurance) web portal is available at <url
+            id="&url-ddpo;"> which displays a table listing all the packages
+of a single developer (including those where the party is listed as
+a co-maintainer). The table gives a good summary about the developer's 
+packages: number of bugs by severity, list of available versions in each
+distribution, testing status and much more including links to any other

 useful information.
        <p>
 useful information.
        <p>

-It is a very good idea to take a look at this table regularly so that
-you don't forget any open bug and so that you don't forget which
+It is a good idea to look up your own data regularly so that
+you don't forget any open bug, and so that you don't forget which

 packages are under your responsibility.
 packages are under your responsibility.

-       <p>
-You will find everything here : <url id="&url-ddpo;">

 
 
    <chapt id="pkgs">Managing Packages
 
 
    <chapt id="pkgs">Managing Packages


@@ -1546,7 +1545,7 @@ inclusion.
 The testing distribution is fed with packages from unstable according to the rules
 explained in <ref id="testing">. However, the release manager may stop the testing
 scripts when he wants to freeze the distribution. In that case, you may want to
 The testing distribution is fed with packages from unstable according to the rules
 explained in <ref id="testing">. However, the release manager may stop the testing
 scripts when he wants to freeze the distribution. In that case, you may want to

-upload to <em>testing-proposed-udaptes</em> to provide fixed packages during the freeze.
+upload to <em>testing-proposed-updates</em> to provide fixed packages during the freeze.

            <p>
 Keep in mind that packages uploaded there are not automatically processed, they
 have to go through the hands of the release manager. So you'd better have a good
            <p>
 Keep in mind that packages uploaded there are not automatically processed, they
 have to go through the hands of the release manager. So you'd better have a good


@@ -1891,7 +1890,7 @@ announce a certain period of time in which the NMU rules are relaxed.
 This usually involves shortening the period during which one is to wait
 before uploading the fixes, and shortening the DELAYED period. It is
 important to notice that even in these so-called "bug squashing party"
 This usually involves shortening the period during which one is to wait
 before uploading the fixes, and shortening the DELAYED period. It is
 important to notice that even in these so-called "bug squashing party"

-times, the NMUer has to file bugs and contact the developer first,
+times, the NMU'er has to file bugs and contact the developer first,

 and act later.
 
       <sect1 id="nmu-guidelines">How to do a source NMU
 and act later.
 
       <sect1 id="nmu-guidelines">How to do a source NMU


@@ -2014,7 +2013,7 @@ changes file.
 
       <sect1 id="ack-nmu">Acknowledging an NMU
        <p>
 
       <sect1 id="ack-nmu">Acknowledging an NMU
        <p>

-If one of your packages has been NMUed, you have to incorporate the
+If one of your packages has been NMU'ed, you have to incorporate the

 changes in your copy of the sources. This is easy, you just have
 to apply the patch that has been sent to you. Once this is done, you
 have to close the bugs that have been tagged fixed by the NMU. You
 changes in your copy of the sources. This is easy, you just have
 to apply the patch that has been sent to you. Once this is done, you
 have to close the bugs that have been tagged fixed by the NMU. You


@@ -2403,14 +2402,14 @@ 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-debian-policy;"
 name="Debian Policy Manual"> for details).  Once you've uploaded
 your <file>debian/control</file> file to replace and conflict with the
 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
+the 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. Do not forget to properly reassign the package's bugs
 at the same time.
        <p>
 against <tt>ftp.debian.org</tt> asking to remove the package with the
 obsolete name. Do not forget to properly reassign the package's bugs
 at the same time.
        <p>

-At other times, you may make a mistake in constructing your package, and
+At other times, you may make a mistake in constructing your package and

 wish to replace it. The only way to do this is to increase the version
 wish to replace it. The only way to do this is to increase the version

-number, and upload a new version. The old version will be expired in
+number and upload a new version. The old version will be expired in

 the usual manner.  Note that this applies to each part of your package,
 including the sources: if you wish to replace the upstream source tarball
 of your package, you will need to upload it with a different version. An
 the usual manner.  Note that this applies to each part of your package,
 including the sources: if you wish to replace the upstream source tarball
 of your package, you will need to upload it with a different version. An


@@ -2640,7 +2639,7 @@ whether it is already a matter of public knowledge.
 There are a few ways a developer can learn of a security problem:
 
 <list compact>
 There are a few ways a developer can learn of a security problem:
 
 <list compact>

-    <item>he notices it on a public forum (mailing list, website, etc.)
+    <item>he notices it on a public forum (mailing list, web site, etc.)

     <item>someone files a bug report
     <item>someone informs him via private email
 </list>
     <item>someone files a bug report
     <item>someone informs him via private email
 </list>


@@ -2675,8 +2674,8 @@ for unstable is public.
 
 <p>
 There are two reasons for releasing information even though secrecy is
 
 <p>
 There are two reasons for releasing information even though secrecy is

-requested: the problem has been known for too long, or the information
-has become public.
+requested: the problem has been known for a while, or that the problem
+or exploit has become public.

 
         <sect2 id="bug-security-advisories">Security Advisories
           <p>
 
         <sect2 id="bug-security-advisories">Security Advisories
           <p>


@@ -2704,29 +2703,29 @@ text. Information that should be in an advisory includes:
   <item>Information on where to obtain the updated packages
 </list>
 
   <item>Information on where to obtain the updated packages
 </list>
 

-         <sect2 id="bug-security-building">Preparing packages to
-         address security issues
+         <sect2 id="bug-security-building">
+            <heading>Preparing packages to address security issues</heading>

          <p>
 One way that you can assist the security team in their duties is to
 provide fixed packages suitable for a security advisory for the stable
 Debian release.
          <p>
  When an update is made to the stable release, care must be taken to
          <p>
 One way that you can assist the security team in their duties is to
 provide fixed packages suitable for a security advisory for the stable
 Debian release.
          <p>
  When an update is made to the stable release, care must be taken to

- avoid changing system behaviour or introducing new bugs.  In order to
+ avoid changing system behavior or introducing new bugs.  In order to

  do this, make as few changes as possible to fix the bug.  Users and
  do this, make as few changes as possible to fix the bug.  Users and

- administrators rely on the exact behaviour of a release once it is
- made, so any change we make can possibly break someone's system.
+ administrators rely on the exact behavior of a release once it is
+ made, so any change that is made might break someone's system.

  This is especially true of libraries: make sure you never change the
  API or ABI, no matter how small the change.
 <p>
 This means that moving to a new upstream version is not a good
  This is especially true of libraries: make sure you never change the
  API or ABI, no matter how small the change.
 <p>
 This means that moving to a new upstream version is not a good

-solution.  Instead, the relevant changes should be backported to the
+solution.  Instead, the relevant changes should be back-ported to the

 version present in the current stable Debian release. Generally,
 upstream maintainers are willing to help if needed.  If not, the
 Debian security team may be able to help.
 <p>
 version present in the current stable Debian release. Generally,
 upstream maintainers are willing to help if needed.  If not, the
 Debian security team may be able to help.
 <p>

-In some cases, it is not possible to backport a security fix, for
-example when large amounts of sourcecode need to be modified or
+In some cases, it is not possible to back-port a security fix, for
+example when large amounts of source code need to be modified or

 rewritten.  If this happens, it may be necessary to move to a new
 upstream version.  However, you must always coordinate that with the
 security team beforehand.
 rewritten.  If this happens, it may be necessary to move to a new
 upstream version.  However, you must always coordinate that with the
 security team beforehand.


@@ -2741,28 +2740,28 @@ When packaging the fix, keep the following points in mind:
 
 <list>
     <item>Make sure you target the right distribution in your
 
 <list>
     <item>Make sure you target the right distribution in your

-    debian/changelog. For stable this is stable-security and for
-    testing this is testing-security. Do not target
-    <em>distribution</em>-proposed-updates!
+    <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
+    testing this is <tt>testing-security</tt>. Do not target
+    <var>distribution</var>-proposed-updates!

 
     <item>Make sure the version number is proper. It must be greater
     than the current package, but less than package versions in later
     distributions.  If in doubt, test it with <tt>dpkg
 
     <item>Make sure the version number is proper. It must be greater
     than the current package, but less than package versions in later
     distributions.  If in doubt, test it with <tt>dpkg

-    --compare-versions</tt>.  For testing, this means there must be
-    a greater version in unstable. If there is none yet (for example,
-    if testing and unstable have the same version) you must upload a
+    --compare-versions</tt>.  For <em>testing</em>, there must be
+    a higher version in <em>unstable</em>. If there is none yet (for example,
+    if <em>testing</em> and <em>unstable</em> have the same version) you must upload a

     new version to unstable first.
 
     <item>Do not make source-only uploads if your package has any
     binary-all packages (do not use the <tt>-S</tt> option to
     new version to unstable first.
 
     <item>Do not make source-only uploads if your package has any
     binary-all packages (do not use the <tt>-S</tt> option to

-    <prgn>dpkg-buildpackage</prgn>).  The buildd infrastructure will
+    <prgn>dpkg-buildpackage</prgn>).  The <prgn>buildd</prgn> infrastructure will

     not build those. This point applies to normal package uploads as
     well.
 
     <item>Always build with full source (use the <tt>-sa</tt> option
     for <prgn>dpkg-buildpackage</prgn>).
 
     not build those. This point applies to normal package uploads as
     well.
 
     <item>Always build with full source (use the <tt>-sa</tt> option
     for <prgn>dpkg-buildpackage</prgn>).
 

-    <item>Be sure to use the exact same .orig.tar.gz as used in the
+    <item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the

     normal archive, otherwise it is not possible to move the security
     fix into the main archives later.
 
     normal archive, otherwise it is not possible to move the security
     fix into the main archives later.
 


@@ -2781,7 +2780,7 @@ prior authorization from the security team.  If the package does not
 exactly meet the team's requirements, it will cause many problems and
 delays in dealing with the unwanted upload.
 <p>
 exactly meet the team's requirements, it will cause many problems and
 delays in dealing with the unwanted upload.
 <p>

-Once you have created and tested the new package, and it has been
+Once you have created and tested the new package and it has been

 approved by the security team, it needs to be uploaded so that it can
 be installed in the archives. For security uploads, the place to
 upload to is
 approved by the security team, it needs to be uploaded so that it can
 be installed in the archives. For security uploads, the place to
 upload to is


@@ -2800,7 +2799,7 @@ be fixes for security problems that cannot be disclosed yet.
 <p>
 If a member of the security team accepts a package, it will be
 installed on security.debian.org as well as the proper
 <p>
 If a member of the security team accepts a package, it will be
 installed on security.debian.org as well as the proper

-<em>distribution</em>-proposed-updates on ftp-master or in the non-US
+<var>distribution</var>-proposed-updates on ftp-master or in the non-US

 archive.
 
       <sect1 id="upload-bugfix">When bugs are closed by new uploads
 archive.
 
       <sect1 id="upload-bugfix">When bugs are closed by new uploads


@@ -2887,8 +2886,8 @@ almost always automatically done by a debhelper script. Furthermore it
 offers enough flexibility to be able to use it in conjunction with
 some hand crafted shell invocations within the <file>rules</file> file.
        <p>
 offers enough flexibility to be able to use it in conjunction with
 some hand crafted shell invocations within the <file>rules</file> file.
        <p>

-You can however decide to not use any helper script, and still write
-some very good <file>rules</file> file. Many examples are available
+You can however decide to not use any helper script and still write
+excellent <file>rules</file> file. Many examples are available

 at <url id="&url-rules-files;">.
 
 <!--
 at <url id="&url-rules-files;">.
 
 <!--


@@ -2980,11 +2979,14 @@ full example.
        /etc/modutils/ for module configuration.
 -->
 
        /etc/modutils/ for module configuration.
 -->
 

-       <sect1 id="bpp-autotools">Packages using autoconf/automake
+       <sect1 id="bpp-autotools">
+          <heading>Packages using
+          <prgn>autoconf</prgn>/<prgn>automake</prgn></heading>

        <p>
        <p>

-Some very good packaging practices for packages using autoconf and/or
-automake have been synthetized in &file-bpp-autotools;. You're strongly
-encouraged to read this file and to follow the given recommandations.
+Some very good packaging practices for packages using
+<prgn>autoconf</prgn> and/or <prgn>automake</prgn> have been
+synthesized in &file-bpp-autotools;. You're strongly encouraged to
+read this file and to follow the given recommendations.

 
 
        <sect1 id="bpp-libraries">Libraries
 
 
        <sect1 id="bpp-libraries">Libraries


@@ -2992,8 +2994,8 @@ encouraged to read this file and to follow the given recommandations.
 Libraries are always difficult to package for various reasons. The policy
 imposes many constraints to ease their maintenance and to make sure
 upgrades are as simple as possible when a new upstream version comes out.
 Libraries are always difficult to package for various reasons. The policy
 imposes many constraints to ease their maintenance and to make sure
 upgrades are as simple as possible when a new upstream version comes out.

-A breakage in a library can result in dozens of dependent packages to
-break...
+A breakage in a library can result in dozens of dependent packages
+breaking.

        <p>
 Good practices for library packaging have been grouped in
 <url id="&url-libpkg-guide;" name="the library packaging guide">.
        <p>
 Good practices for library packaging have been grouped in
 <url id="&url-libpkg-guide;" name="the library packaging guide">.


@@ -3004,7 +3006,7 @@ Several subsets of packages have special sub-policies and corresponding
 packaging rules and practices:
 <list>
     <item>
 packaging rules and practices:
 <list>
     <item>

-Perl related packages have a <url name="perl policy" id="&url-perl-policy;">,
+Perl related packages have a <url name="Perl policy" id="&url-perl-policy;">,

 some examples of packages following that policy are
 <package>libdbd-pg-perl</package> (binary perl module) or 
 <package>libmldbm-perl</package> (arch independent perl module).
 some examples of packages following that policy are
 <package>libdbd-pg-perl</package> (binary perl module) or 
 <package>libmldbm-perl</package> (arch independent perl module).


@@ -3018,7 +3020,7 @@ name="emacs policy">.
 Java related packages have their <url id="&url-java-policy;"
 name="java policy">.
     <item>
 Java related packages have their <url id="&url-java-policy;"
 name="java policy">.
     <item>

-Ocaml related packages have their ocaml policy: &file-ocaml-policy; (in
+Ocaml related packages have their Ocaml policy: &file-ocaml-policy; (in

 the <package>ocaml</package> package). A good example is the <package>camlzip</package>
 source package.
 </list>
 the <package>ocaml</package> package). A good example is the <package>camlzip</package>
 source package.
 </list>


@@ -3029,7 +3031,7 @@ source package.
        <sect1 id="config-wise-debconf">The wise use of debconf
        <p>
 Debconf is a configuration management system, it is used by all the
        <sect1 id="config-wise-debconf">The wise use of debconf
        <p>
 Debconf is a configuration management system, it is used by all the

-various packaging scripts (postinst mainly) to request feedback from the
+various packaging scripts (<file>postinst</file> mainly) to request feedback from the

 user concerning how to configure the package. Direct user interactions
 must now be avoided in favor of debconf interaction. This will enable
 non-interactive installations in the future.
 user concerning how to configure the package. Direct user interactions
 must now be avoided in favor of debconf interaction. This will enable
 non-interactive installations in the future.


@@ -3093,7 +3095,7 @@ ways, often really critical ways, to contribute to Debian beyond
 simply creating and maintaining packages.
     <p>
 As a volunteer organization, Debian relies on the discretion of its
 simply creating and maintaining packages.
     <p>
 As a volunteer organization, Debian relies on the discretion of its

-members in choosing what they want to work on, and choosing what is
+members in choosing what they want to work on and in choosing

 the most critical thing to spend their time on.
 
     <sect id="submit-bug">
 the most critical thing to spend their time on.
 
     <sect id="submit-bug">


@@ -3178,7 +3180,7 @@ patch, or if you will deal yourself with the bug, please explain that in
 the BTS.
        <p>
 People participating in the party have special rules for NMU, they can
 the BTS.
        <p>
 People participating in the party have special rules for NMU, they can

-NMU withour prior notice if they upload their NMU to
+NMU without prior notice if they upload their NMU to

 DELAYED/3-day at least. All other NMU rules applies as usually, they
 should send the patch of the NMU in the BTS (in one of the open bugs
 fixed by the NMU or in a new bug tagged fixed). They should
 DELAYED/3-day at least. All other NMU rules applies as usually, they
 should send the patch of the NMU in the BTS (in one of the open bugs
 fixed by the NMU or in a new bug tagged fixed). They should


@@ -3266,7 +3268,7 @@ the package meets minimum Debian standards.  That implies that you
 must build and test the package on your own system before uploading.
        <p>
 You can not simply upload a binary <file>.deb</file> from the sponsoree. In
 must build and test the package on your own system before uploading.
        <p>
 You can not simply upload a binary <file>.deb</file> from the sponsoree. In

-theory, you should only ask only for the diff file, and the location of the
+theory, you should only ask only for the diff file and the location of the

 original source tarball, and then you should download the source and apply
 the diff yourself. In practice, you may want to use the source package
 built by your sponsoree. In that case, you have to check that they haven't
 original source tarball, and then you should download the source and apply
 the diff yourself. In practice, you may want to use the source package
 built by your sponsoree. In that case, you have to check that they haven't


@@ -3437,7 +3439,7 @@ changes into the repository.
        <p>
 These utilities provide an infrastructure to facilitate the use of CVS
 by Debian maintainers. This allows one to keep separate CVS branches
        <p>
 These utilities provide an infrastructure to facilitate the use of CVS
 by Debian maintainers. This allows one to keep separate CVS branches

-of a package for <em>stable</em>, <em>unstable</em>, and possibly
+of a package for <em>stable</em>, <em>unstable</em> and possibly

 <em>experimental</em> distributions, along with the other benefits of
 a version control system.
 
 <em>experimental</em> distributions, along with the other benefits of
 a version control system.