chiark / gitweb /
changed needlessly FTP URIs to HTTP; added debian-project
[developers-reference.git] / developers-reference.sgml
index 8f2745bc58f53366f68a1627d52536a02e7c241e..3b1206feb930bff99b49e0076307e098b909c228 100644 (file)
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.114 $">
+  <!entity cvs-rev "$Revision: 1.121 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -38,7 +38,7 @@
 
       <copyright>
        <copyrightsummary>
-copyright &copy;1998&ndash;2002 Adam Di Carlo</copyrightsummary>
+copyright &copy;1998&mdash;2002 Adam Di Carlo</copyrightsummary>
        <copyrightsummary>
 copyright &copy;1997, 1998 Christian Schwarz</copyrightsummary>
        <p>
@@ -54,7 +54,7 @@ General Public License for more details.
        <p>
 A copy of the GNU General Public License is available as &file-GPL; in
 the &debian-formal; distribution or on the World Wide Web at <url
-id="&url-gpl;" name="the GNU website">.  You can also obtain it by
+id="&url-gpl;" name="the GNU web site">.  You can also obtain it by
 writing to the &fsf-addr;.
 
     <toc detail="sect1">
@@ -111,7 +111,7 @@ to &email-debian-devel-req;.  In case of problems, contact the list
 administrator at &email-listmaster;.  More information on available
 mailing lists can be found in <ref id="mailing-lists">.
 &email-debian-devel-announce; is another list which is mandatory
-for anyone who wish to follow Debian's development.
+for anyone who wishes to follow Debian's development.
        <p>
 You should subscribe and lurk (that is, read without posting) for a
 bit before doing any coding, and you should post about your intentions
@@ -128,8 +128,8 @@ should get in contact with existing Debian maintainers who are working
 on similar tasks.  That way, you can learn from experienced developers.
 For example, if you are interested in packaging existing software for
 Debian you should try to get a sponsor.  A sponsor will work together
-with you on your package and upload it to the Debian archive once he
-is happy with the packaging work you have done.  You can find a sponsor
+with you on your package and upload it to the Debian archive once they
+are happy with the packaging work you have done.  You can find a sponsor
 by mailing the &email-debian-mentors; mailing list, describing your
 package and yourself and asking for a sponsor (see <ref id="sponsoring">
 for more information on sponsoring).  On the other hand, if you are
@@ -201,7 +201,7 @@ OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC
 2440">.
        <p>
 The recommended public key algorithm for use in Debian development
-work is the DSA (sometimes call ``DSS'' or ``DH/ElGamal'').  Other key
+work is DSA (sometimes call ``DSS'' or ``DH/ElGamal'').  Other key
 types may be used however.  Your key length must be at least 1024
 bits; there is no reason to use a smaller key, and doing so would be
 much less secure.  Your key must be signed with at least your own user
@@ -272,7 +272,7 @@ available in <ref id="newmaint">.
 
       <sect id="user-maint">Maintaining your Debian information
        <p>
-There's a LDAP database containing many informations concerning all
+There's a LDAP database containing information about all
 developers, you can access it at <url id="&url-debian-db;">. You can
 update your password (this password is propagated to most of the machines
 that are accessible to you), your address, your country, the latitude and
@@ -288,13 +288,13 @@ You have to keep the information available there up-to-date.
       <sect id="key-maint">Maintaining your public key
        <p>
 Be very careful with your private keys.  Do not place them on any
-public servers or multiuser machines, such as
-<tt>&master-host;</tt>.  Back your keys up; keep a copy offline.
+public servers or multiuser machines, such as the Debian servers
+(see <ref id="server-machines">).  Back your keys up; keep a copy offline.
 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 key ring 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.
@@ -317,8 +317,8 @@ there. If you want to follow the debate preceding a vote, you
 may want to subscribe to &email-debian-vote;.
        <p>
 The list of all the proposals (past and current) is available on the
-web at <url id="url-vote">. You will find there additional information
-about how to make a vote proposal.
+<url id="&url-vote;" name="Debian Voting Information"> page. You will find
+there additional information about how to make a vote proposal.
 
 
       <sect id="inform-vacation">Going on vacation gracefully
@@ -402,35 +402,70 @@ emailing to &email-debian-keyring;.
    <chapt id="resources">Resources for Debian Developers
      <p>
 In this chapter you will find a very brief road map of the Debian
-mailing lists, the main Debian servers, other Debian machines
+mailing lists, the Debian machines
 which may be available to you as a developer, and all the other
 resources that are available to help you in your maintainer work.
 
       <sect id="mailing-lists">Mailing lists
        <p>
-The mailing list server is at <tt>&lists-host;</tt>.  Mail
+The mailing list server is at <tt>&lists-host;</tt>.
+       <p>
+Online archives of mailing lists are available at <url
+id="&url-lists-archives;">.
+
+       <sect1 id="core-devel-mailing-lists">Core development mailing lists
+       <p>
+The core Debian mailing lists that developers should use are:
+<list>
+  <item>&email-debian-devel-announce;, used to announce important things to
+        developers.
+        All developers are expected to be subscribed to this list.
+  </item>
+  <item>&email-debian-devel;, used to discuss various development related
+        technical issues.
+  </item>
+  <item>&email-debian-policy;, where the Debian Policy is discussed and
+        voted on.
+  </item>
+  <item>&email-debian-project;, used to discuss various non-technical
+        issues related to the project.
+  </item>
+</list>
+       <p>
+There are
+other mailing lists available for a variety of special topics; see
+<url id="&url-debian-lists-subscribe;"> for a list.
+
+       <sect1 id="mailing-lists-subunsub">Subscribing and unsubscribing
+       <p>
+To subscribe to or unsubscribe from any of the Debian mailing lists, email
 <tt>debian-<var>foo</var>-REQUEST@&lists-host;</tt>, where
 <tt>debian-<var>foo</var></tt> is the name of the list, with the word
 <tt>subscribe</tt> in the <em>Subject</em> to subscribe to the list or
-<tt>unsubscribe</tt> to unsubscribe.  More detailed instructions on
-how to subscribe and unsubscribe to the mailing lists can be found at
-<url id="&url-debian-lists-subscribe;">, <url id="&url-debian-lists;">
-or locally in &file-mail-lists; if you have the
-<package>doc-debian</package> package installed.
+<tt>unsubscribe</tt> to unsubscribe.
+       <p>
+If you prefer to use a web page to subscribe to multiple mailing lists,
+there's one at <url id="&url-debian-lists-subscribe;">.
+       <p>
+You can download the current list of mailing lists and basic usage
+instructions from <url id="&url-debian-lists;">
+or install the <package>doc-debian</package> package and have it
+locally in &file-mail-lists;.
+
+       <sect1 id="mailing-lists-rules">Basic rules for use
        <p>
 When replying to messages on the mailing list, please do not send a
 carbon copy (<tt>CC</tt>) to the original poster unless they explicitly
 request to be copied.  Anyone who posts to a mailing list should read
 it to see the responses.
        <p>
-The following are the core Debian mailing lists: &email-debian-devel;,
-&email-debian-policy;, &email-debian-user;, &email-debian-private;,
-&email-debian-announce;, and &email-debian-devel-announce;.  All
-developers are expected to be subscribed to at least
-&email-debian-devel-announce;.  There are
-other mailing lists available for a variety of special topics; see
-<url id="&url-debian-lists-subscribe;"> for a list.  Cross-posting
-(sending the same message to multiple lists) is discouraged.
+Cross-posting (sending the same message to multiple lists) is discouraged.
+As ever on the net, please trim down the quoting of articles you're
+replying to.  In general, please adhere to the usual conventions for
+posting messages. Please read the <url name="code of conduct"
+id="&url-debian-lists;"> for more information.
+
+       <sect1 id="mailing-lists-special">Special lists
        <p>
 &email-debian-private; is a special mailing list for private
 discussions amongst Debian developers.  It is meant to be used for
@@ -439,20 +474,13 @@ As such, it is a low volume list, and users are urged not to use
 &email-debian-private; unless it is really necessary.  Moreover, do
 <em>not</em> forward email from that list to anyone.  Archives of this
 list are not available on the web for obvious reasons, but you can see
-them using your shell account on <tt>&master-host;</tt> and looking
+them using your shell account on <tt>lists.debian.org</tt> and looking
 in the <file>~debian/archive/debian-private</file> directory.
        <p>
 &email-debian-email; is a special mailing list used as a grab-bag 
 for Debian related correspondence such as contacting upstream authors
 about licenses, bugs, etc. or discussing the project with others where it
 might be useful to have the discussion archived somewhere.
-       <p>
-As ever on the net, please trim down the quoting of articles you're
-replying to.  In general, please adhere to the usual conventions for
-posting messages.
-       <p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
 
       <sect id="irc-channels">IRC channels
        <p>
@@ -465,11 +493,13 @@ The main channel <em>#debian-devel</em> is very active since more
 than 150 persons are always logged in. It's a channel for people who work
 on Debian, it's not a support channel (there's <em>#debian</em> for that).
 It is however open to anyone who wants to lurk (and learn). Its topic is
-always full of interesting informations. Since it's an open channel, you
+always full of interesting information. Since it's an open channel, you
 should not speak there of issues that are discussed in
 &email-debian-private;. There's a key protected channel
 <em>#debian-private</em> for that purpose. The key is available 
-in the archives of debian-private in <file>&master-host;:&file-debian-private-archive;</file>, just <prgn>zgrep</prgn> for <em>#debian-private</em> in
+in the archives of debian-private in
+<file>master.debian.org:&file-debian-private-archive;</file>,
+just <prgn>zgrep</prgn> for <em>#debian-private</em> in
 all the files.
        <p>
 There are other additional channels dedicated to specific subjects.
@@ -488,47 +518,65 @@ French speaking people interested in Debian's development.
 
       <sect id="doc-rsrcs">Documentation
        <p>
-This document contains many informations very useful to Debian developers,
+This document contains a lot of information very useful to Debian developers,
 but it can not contain everything. Most of the other interesting documents
 are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.
 Take the time to browse all the links, you will learn many more things.
 
-      <sect id="server-machines">Debian servers
+
+      <sect id="server-machines">Debian machines
+       <p>
+Debian has several computers working as servers, most of which serve
+critical functions in the Debian project. Most of the machines are used
+for porting activities, and they all have a permanent connection to the
+Internet.
+       <p>
+Most of the machines are available for individual developers to use,
+as long as the developers follow the rules set forth in the
+<url name="Debian Machine Usage Policies" id="&url-dmup;">.
        <p>
-Debian servers are well known servers which serve critical functions
-in the Debian project.  Every developer should know what these servers
-are and what they do.
+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
+volunteers.
+       <p>
+Please take care to protect your Debian passwords and SSH keys installed on
+Debian machines. Avoid login or upload methods which send passwords over
+the Internet in the clear, such as telnet, FTP, POP etc.
+       <p>
+Please do not put any material that doesn't relate to Debian on the Debian
+servers, unless you have prior permission.
+       <p>
+The current list of Debian machines is available at
+<url id="&url-devel-machines;">. That web page contains machine names,
+contact information, information about who can log in, SSH keys etc.
        <p>
 If you have a problem with the operation of a Debian server, and you
 think that the system operators need to be notified of this problem,
-please find the contact address for the particular machine at <url
-id="&url-devel-machines;">.  If you have a non-operating problems
-(such as packages to be remove, suggestions for the web site, etc.),
+the Debian system administrator team is reachable at
+<email>debian-admin@lists.debian.org</email>.
+       <p>
+If you have a problem with a certain service, not related to the system
+administration (such as packages to be removed from the archive,
+suggestions for the web site, etc.),
 generally you'll report a bug against a ``pseudo-package''.  See <ref
 id="submit-bug"> for information on how to submit bugs.
 
-      <sect1 id="servers-master">The master server
+      <sect1 id="servers-bugs">The bugs server
        <p>
-<tt>&master-host;</tt> is the canonical location for the Bug Tracking
+<tt>bugs.debian.org</tt> is the canonical location for the Bug Tracking
 System (BTS).  If you plan on doing some statistical analysis or
 processing of Debian bugs, this would be the place to do it.  Please
 describe your plans on &email-debian-devel; before implementing
 anything, however, to reduce unnecessary duplication of effort or
 wasted processing time.
        <p>
-All Debian developers have accounts on <tt>&master-host;</tt>.
-Please take care to protect your password to this machine.  Try to
-avoid login or upload methods which send passwords over the Internet
-in the clear.
-       <p>
-If you find a problem with <tt>&master-host;</tt> such as disk
-full, suspicious activity, or whatever, send an email to
-&email-debian-admin;.
+All Debian developers have accounts on <tt>bugs.debian.org</tt>.
 
       <sect1 id="servers-ftp-master">The ftp-master server
        <p>
-The ftp-master server, <tt>&ftp-master-host;</tt> (or
-<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian
 archive (excluding the non-US packages). Generally, package uploads
 go to this server; see <ref id="upload">.
        <p>
@@ -537,34 +585,59 @@ bugs against the <package>ftp.debian.org</package> pseudo-package or
 an email to &email-ftpmaster;, but also see the procedures in
 <ref id="archive-manip">.
 
-      <sect1 id="servers-www">The WWW server
+      <sect1 id="servers-non-us">The non-US server
        <p>
-The main web server, <tt>&www-host;</tt>, is also known as
-<tt>klecker.debian.org</tt>.  All developers are given accounts on this
-machine.
+The non-US server, <tt>non-us.debian.org</tt>,
+holds the canonical copy of the non-US part of the Debian archive.
+If you need to upload a package into one of the non-US sections, upload it
+to this server; see <ref id="upload-non-us">.
        <p>
-If you have some Debian-specific information which you want to serve
-up on the web, you can do this by putting material in the
-<file>public_html</file> directory under your home directory.  You should
-do this on <tt>klecker.debian.org</tt>. Any material you put in those areas
-are accessible via the URL
-<tt>http://people.debian.org/~<var>user-id</var>/</tt>.
-You should only use this particular location because it will be backed up,
-whereas on other hosts it won't. Please do not put any material on Debian
-servers not relating to Debian, unless you have prior permission.
-Send mail to &email-debian-devel; if you have any questions.
+Problems with the non-US package archive should generally be submitted as
+bugs against the <package>nonus.debian.org</package> pseudo-package (notice
+the lack of hyphen between "non" and "us" in the pseudo-package name
+&mdash; that's for backwards compatibility). Remember to check whether or
+not someone else has already reported the problem on the
+<url id="http://bugs.debian.org/nonus.debian.org" name="Bug Tracking System">.
+
+      <sect1 id="servers-www">The www-master server
+       <p>
+The main web server is <tt>www-master.debian.org</tt>.
+It holds the official web pages, the face
+of Debian for most newbies.
        <p>
 If you find a problem with the Debian web server, you should generally
 submit a bug against the pseudo-package,
-<package>www.debian.org</package>.  First check whether or not someone
+<package>www.debian.org</package>. Remember to check whether or not someone
 else has already reported the problem on the
 <url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
 
+      <sect1 id="servers-people">The people web server
+       <p>
+<tt>people.debian.org</tt> is the server used
+for developers' own web pages about anything related to Debian.
+       <p>
+If you have some Debian-specific information which you want to serve
+on the web, you can do this by putting material in the
+<file>public_html</file> directory under your home directory on
+<tt>people.debian.org</tt>.
+This will be accessible at the URL
+<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.
+       <p>
+You should only use this particular location because it will be backed up,
+whereas on other hosts it won't.
+       <p>
+Usually the only reason to use a different host is when you need to publish
+materials subject to the U.S. export restrictions, in which case you can use
+one of the other servers located outside the United States, such as the
+aforementioned <tt>non-us.debian.org</tt>.
+       <p>
+Send mail to &email-debian-devel; if you have any questions.
 
       <sect1 id="servers-cvs">The CVS server
        <p>
-<tt>cvs.debian.org</tt> is also known as <tt>klecker.debian.org</tt>,
-discussed above.  If you need to use a publicly accessible CVS
+Our CVS server is located on <tt>cvs.debian.org</tt>.
+       <p>
+If you need to use a publicly accessible CVS
 server, for instance, to help coordinate work on a package between
 many different developers, you can request a CVS area on the server.
          <p>
@@ -578,7 +651,7 @@ To request a CVS area, send a request via email to
 the Debian account that should own the CVS root area, and why you need it.
 
 
-      <sect1 id="devel-db">The Developers Database
+    <sect id="devel-db">The Developers Database
        <p>
 The Developers Database, at <url id="&url-debian-db;">, is an LDAP
 directory for managing Debian developer attributes.  You can use this
@@ -611,21 +684,6 @@ interested in helping Debian.  As such, developers generally do not
 have accounts on these machines.
 
 
-      <sect id="other-machines">Other Debian developer machines
-       <p>
-There are other Debian machines which may be made available to you.
-You can use these 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 local maintainers.  Usually these machines are run by
-volunteers.  Generally, these machines are for porting activities.
-       <p>
-Aside from the servers mentioned in <ref id="server-machines">, there
-is a list of machines available to Debian developers at <url
-id="&url-devel-machines;">.
-
-
-
     <sect id="archive">The Debian archive
        <p>
 The &debian-formal; distribution consists of a lot of packages
@@ -641,14 +699,15 @@ As you can see, the top-level directory contains two directories,
 packages actually are, and which is handled by the archive maintenance
 database and the accompanying programs. The former contains the
 distributions, <em>stable</em>, <em>testing</em> and <em>unstable</em>.
-Each of those distribution directories is divided in equivalent
-subdirectories purpose of which is equal, so we will only explain how it
-looks in stable. The <file>Packages</file> and <file>Sources</file> files in the
+The <file>Packages</file> and <file>Sources</file> files in the
 distribution subdirectories can reference files in the <file>pool/</file>
-directory.
+directory. The directory tree below each of the distributions is arranged
+in an identical manner.  What we describe below for <em>stable</em> is
+equally applicable to the <em>unstable</em> and <em>testing</em>
+distributions. 
        <p>
 <file>dists/stable</file> contains three directories, namely <file>main</file>,
-<file>contrib</file>, and <file>non-free</file>.
+<file>contrib</file>, and <file>non-free</file>. 
        <p>
 In each of the areas, there is a directory for the source packages
 (<file>source</file>) and a directory for each supported architecture
@@ -832,7 +891,7 @@ that time (although it can be found at <tt>&archive-host;</tt>).
 This development cycle is based on the assumption that the
 <em>unstable</em> distribution becomes <em>stable</em> after passing a
 period of being in <em>testing</em>.  Even once a distribution is
-considered stable, a few bugs inevitably remain &mdash that's why the
+considered stable, a few bugs inevitably remain &mdash; that's why the
 stable distribution is updated every now and then. However, these
 updates are tested very carefully and have to be introduced into the
 archive individually to reduce the risk of introducing new bugs.  You
@@ -887,7 +946,7 @@ New software which isn't likely to damage your system can go directly into
 <em>unstable</em>.
          <p>
 An alternative to <em>experimental</em> is to use your personal web space
-on <tt>people.debian.org</tt> (<tt>klecker.debian.org</tt>).
+on <tt>people.debian.org</tt>.
 
 
       <sect1 id="codenames">Release code names
@@ -935,15 +994,15 @@ 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 <file>unchecked</file>
-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 <file>accepted</file> directory. If it is the first upload of
-the package then it is moved in a <file>new</file> directory waiting an
-approval of the ftpmasters. If the package contains files to be installed
-"by-hand" is is moved in the <file>byhand</file> directory waiting a manual
-installation by the ftpmasters. Otherwise, if any error has been detected,
+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
+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
+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>
 Once the package is accepted the system sends a confirmation
@@ -980,10 +1039,10 @@ be moved in <file>4-day</file>). 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 <file>DELAYED/<var>x</var>-day</file> 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.
+That leaves the corresponding number of days for the maintainer
+to react and upload another fix themselves if they are not
+completely satisfied with the NMU. Alternatively they can remove
+the NMU.
        <p>
 The use of that delayed feature can be simplified with a bit
 of integration with your upload tool.  For instance, if you use 
@@ -1042,7 +1101,7 @@ the <prgn>grep-excuses</prgn> program part of the
 to keep someone informed of the progression of his packages in testing.
        <p>
 The <file>update_excuses</file> file does not always give the precise reason
-why the package is refused, one may have to find it by himself by looking
+why the package is refused, one may have to find it on their own 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.
@@ -1057,8 +1116,8 @@ contacted, and he will force the inclusion of the packages.
 
       <sect1 id="pkg-info-web">On the web
        <p>
-Each package has several dedicated web pages that contains many
-informations. <tt>http://&packages-host;/<var>package-name</var></tt>
+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,
@@ -1548,7 +1607,7 @@ maintenance software will process it by running <prgn>dinstall</prgn>
 on your changes file: <example>dinstall -n foo.changes</example>.
 Note that <prgn>dput</prgn> can do this for you automatically.
 
-       <sect2 id="upload-non-us">Uploading to <tt>non-US</tt> (pandora)
+       <sect2 id="upload-non-us">Uploading to <tt>non-US</tt>
          <p>
 As discussed above, export controlled software should not be uploaded
 to <tt>ftp-master</tt>.  Instead, upload the package to
@@ -1831,8 +1890,8 @@ Make sure your patch is as small and as non-disruptive as it can be.
            <item>
 Upload your package to incoming in <file>DELAYED/7-day</file> (cf.
 <ref id="delayed-incoming">), send the final patch to the maintainer via
-the BTS, and explain him that he has 7 days to react if he wants to cancel
-the NMU.
+the BTS, and explain to them that they have 7 days to react if they want
+to cancel the NMU.
            <item>
 Follow what happens, you're responsible for any bug that you introduced
 with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)
@@ -1885,11 +1944,7 @@ absolutely necessary for someone other than the usual maintainer to
 make a release based on a new upstream version then the person making
 the release should start with the <var>debian-revision</var> value
 `0.1'.  The usual maintainer of a package should start their
-<var>debian-revision</var> numbering at `1'.  Note that if you do
-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').
+<var>debian-revision</var> numbering at `1'. 
 
 
        <sect2 id="nmu-changelog">
@@ -1972,10 +2027,10 @@ BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog
 entry of your next upload.
        <p>
 In any case, you should not be upset by the NMU. An NMU is not a
-personal attack against the maintainer. It is just the proof that
-someone cares enough about the package and was willing to help
-you in your work. You should be thankful to him and you may want to
-ask him if he would be interested to help you on a more frequent
+personal attack against the maintainer. It is a proof that
+someone cares enough about the package and that they were willing to help
+you in your work, so you should be thankful. You may also want to
+ask them if they would be interested to help you on a more frequent
 basis as co-maintainer or backup maintainer
 (see <ref id="collaborative-maint">).
 
@@ -2400,8 +2455,8 @@ automatically once you upload a new version with an updated
 <tt>Maintainer:</tt> field, although it can take a few hours after the
 upload is done. If you do not expect to upload a new version for a while,
 you can use <ref id="pkg-tracking-system"> to get the bug reports. However,
-make sure that the old maintainer is not embarrassed by the fact that
-he will continue to receive the bugs during that time.
+make sure that the old maintainer has no problem with the fact that
+they will continue to receive the bugs during that time.
 
 
     <sect id="bug-handling">Handling package bugs
@@ -2481,7 +2536,7 @@ give an informative error message. This is an issue that may need
 to be brought to the upstream author.
     <p>
 If the bug submitter disagree with your decision to close the bug,
-he may reopen it until you find an agreement on how to handle it.
+they may reopen it until you find an agreement on how to handle it.
 If you don't find any, you may want to tag the bug <tt>wontfix</tt>
 to let people know that the bug exists but that it won't be corrected.
 If this situation is unacceptable, you (or the submitter) may want to
@@ -2691,8 +2746,8 @@ automatically done by <prgn>dh_installdebconf</prgn> (package
 do the same with <prgn>debconf-mergetemplate</prgn>
 (package <package>debconf-utils</package>). 
        <p>
-When the package maintainer needs to update the templates file, he only
-changes <file>debian/templates</file>.  When English strings in this file
+When the package maintainer needs to update the templates file, they only
+change <file>debian/templates</file>.  When English strings in this file
 and in <file>debian/templates.xx</file> differ, translators do know that
 their translation is outdated.
        <p>
@@ -2786,7 +2841,7 @@ It is something that you must read if you decide to use debconf.
            <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
+available to the user before they install it. As such, it should
 provide all the required information to let him decide whether
 to install the package.
            <p>
@@ -2849,7 +2904,7 @@ out all the bugs you submitted, you just have to visit
       <sect1 id="submit-many-bugs">Reporting lots of bugs at once
        <p>
 Reporting a great number of bugs for the same problem on a great
-number of different packages &mdash i.e., more than 10 &mdash is a deprecated
+number of different packages &mdash; i.e., more than 10 &mdash; is a deprecated
 practice.  Take all possible steps to avoid submitting bulk bugs at
 all.  For instance, if checking for the problem can be automated, add
 a new check to <package>lintian</package> so that an error or warning
@@ -2890,8 +2945,8 @@ If you do not get a reply after a few weeks you should collect all
 useful information about this maintainer. Start by logging into 
 the <url id="&url-debian-db;" name="Debian Developer's Database">
 and doing a full search to check whether the maintainer is on vacation
-and when he was last seen. Collect any important package names
-he maintains and any Release Critical bugs filled against them.
+and when they were last seen. Collect any important package names
+they maintain and any Release Critical bugs filed against them.
       <p>
 Send all this information to &email-debian-qa;, in order to let the 
 QA people do whatever is needed.
@@ -2911,7 +2966,7 @@ email the maintainer, whatever their individual email address (or
 addresses) may be.  Replace <tt>&lt;package&gt;</tt> with the name of
 a source or a binary package.
       <p>
-You may also be interested by contacting the persons who are
+You may also be interested in contacting the persons who are
 subscribed to a given source package via <ref id="pkg-tracking-system">.
 You can do so by using the <tt>&lt;package-name&gt;@&pts-host;</tt>
 email address.
@@ -2962,9 +3017,9 @@ 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
 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 he hasn't
-altered the upstream files in the <file>.orig.tar.gz</file> file that he's
-providing.
+built by your sponsoree. In that case, you have to check that they haven't
+altered the upstream files in the <file>.orig.tar.gz</file> file that
+they're providing.
        <p>
 Do not be afraid to write the sponsoree back and point out changes
 that need to be made.  It often takes several rounds of back-and-forth