chiark / gitweb /
fixed bug closing example, closes: #71198 ;) and updated the perl regexp from current...
[developers-reference.git] / developers-reference.sgml
index 40e198746cabc6c1d055a1c4a68eece2b8e07e7a..b08860ffa4ef06abfd31bec874ef0f92508f5514 100644 (file)
@@ -5,7 +5,7 @@
   <!-- common, language independant entities -->
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.37 $">
+  <!entity cvs-rev "$Revision: 1.42 $">
 
   <!-- if you are translating this document, please notate the RCS
        revision of the developers reference here -->
@@ -71,7 +71,7 @@ packages (<ref id="archive-manip">); and how to handle bug reports
 The resources discussed in this reference include the mailing lists
 and servers (<ref id="servers">); a discussion of the structure of the
 Debian archive (<ref id="archive">); explanation of the different
-servers which accept package uploads (<ref id="upload-master">); and a
+servers which accept package uploads (<ref id="upload-ftp-master">); and a
 discussion of resources which can help maintainers with the quality of
 their packages (<ref id="tools">).
       <p>
@@ -132,8 +132,11 @@ careful about being compromised.  Therefore, we need to verify new
 maintainers before we can give them accounts on our servers and
 letting them upload packages.
        <p>
-Registration requires that the following information be sent to
-&email-new-maintainer; as part of the registration application:
+Registration requires that the following information be sent in
+appropriate steps described at <url id="&url-newmaint-checklist;"
+                                   name="Checklist for applicants">
+after the initial contact to &email-new-maintainer:
+
 <list>
            <item>
 Your name.
@@ -229,13 +232,15 @@ Once you have all your information ready, and your public key is
 available on public key servers, send a message to
 &email-new-maintainer; to register as an offical Debian developer so
 that you will be able to upload your packages.  This message must
-contain all the information discussed above.  The message must also
-contain your public key (extracted using <tt>gpg --armor --export
-<var>user_id</var></tt> in the case of <prgn>gpg</prgn>) for the
-database of keys which is distributed from <url
-id="url-debian-keyring;"> and the <package>debian-keyring</package>
-package.  Please be sure to sign your request message with your chosen
-public key.
+contain your name and your valid e-mail address.  All the information
+discussed above is required after your Application Manager is
+assigned.  Application Manager is your agent in the registration
+process, and you can always ask him about the status of your
+application. You can check the <url id="&url-newmaint-db;"
+name="Application StatusBoard"> as well.
+       <p>
+For more details, please consult <url id="&url-newmaint;" name="New
+Maintainer's Corner"> at the Debian web site.
        <p>
 Once this information is received and processed, you should be
 contacted with information about your new Debian maintainer account.
@@ -258,7 +263,22 @@ Those who prefer one-on-one help (e.g., via private email) should also
 post to that list and an experienced developer will volunteer to help.
 
 
-    <chapt id="user-maint">Maintaining Your Debian Information
+    <chapt id="developer-duties">Debian Developer's Duties
+
+      <sect id="user-maint">Maintaining Your Debian Information
+       <p>
+There's a LDAP database containing many informations concerning 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 adress, your country, the latitude and
+longitude from the point where you live, phone and fax numbers, your
+preferred shell, your IRC nickname, your web page and the email that
+you're using as alias for your debian.org email. Most of the information
+is not accessible to the public, for more details about this
+database, please read its online documentation that you can find
+here : <url id="&url-debian-db-doc;">.
+       <p>
+You have to keep the information available there up to date.
 
       <sect id="key-maint">Maintaining Your Public Key
        <p>
@@ -268,14 +288,76 @@ public servers or multiuser machines, such as
 Read the documentation that comes with your software; read the <url
 id="&url-pgp-faq;" name="PGP FAQ">.
        <p>
-If you add or remove signatures from your public key, or add or remove
-user identities, you need to update the key servers and mail your
-public key to &email-debian-keyring;.  The same key extraction
-routines discussed in <ref id="registering"> apply.
+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
+<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.
        <p>
 You can find a more in-depth discussion of Debian key maintenance in
 the documentation for the <package>debian-keyring</package> package.
 
+      <sect id="inform-vacation">Going On Vacation Gracefully
+       <p>
+Most of the developers take vacation, usually this means that they can't
+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 your package if a big problem (release
+critical bugs, security update, ...) occurs while you're on vacation.
+       <p>
+In order to inform the other developers, there's two things that you should do.
+First send a mail to &email-debian-private; giving the period of time when
+you will be on vacation, you can also give some special instructions on what to
+do if any problem occurs. Next you should update your information
+available in the Debian LDAP database and mark yourself as « on vacation »
+(this information is only accessible to debian developers). Don't forget
+to remove the « on vacation » flag when you come back.
+
+      <sect id="upstream-coordination">Coordination With Upstream Developers
+       <p>
+A big part of your job as Debian maintainer will be to stay in contact
+with the upstream developers since you'll have to share information that
+you get from the Bug Tracking System. It's not your job to fix non-Debian
+specific bugs so you have to forward the bugs to the upstream developers
+(of course, if you are able to fix them, you can ...). This way the bug
+may be corrected when the next upstream version comes out. From time to
+time, you may get a patch attached to a bug report, you have to send the
+patch upstream and make sure that it gets included (if the authors accept
+the proposed fix). 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 developers which can be included 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.
+
+      <sect id="rc-bugs">Managing Release Critical Bugs
+        <p>
+Release Critical Bugs (RCB) are the bugs of severity «&nbsp;critical&nbsp;», 
+«&nbsp;grave&nbsp;» and «&nbsp;important&nbsp;». Those bugs can delay
+the Debian release and/or can justify the removal of a package at freeze
+time. That's why those bugs needs to be corrected as fast as possible.
+You must be aware that some developers who are part of the <url
+id="&url-debian-qa;" name="Debian Quality Assurance"> effort are following
+those bugs and try to help you each time they can. But if you can't
+fix such bugs within 2 weeks, you should either ask for help by sending a
+mail to the Quality Assurance (QA) group (&email-debian-qa;) or 
+justify yourself and gives your plan to fix it by sending a mail to the
+concerned bug report. Otherwise people from the QA group may want to do a
+Non Maintainer Upload (NMU) after trying to contact you (they might wait
+not as long as usually before they do their NMU if they have seen no
+recent activity from you on the BTS).
+
+      <sect id="qa-effort">Quality Assurance Effort
+       <p>
+Even if there is a dedicated group of people for Quality Assurance, QA is
+not reserved to them. You can participate to this effort by keeping your
+packages as bug free as possible, as lintian-clean (see <ref
+id="lintian-reports">) as possible. If you think that it's quite impossible,
+then you should consider orphaning (see <ref id="orphaning">) some of your
+packages so that you can do a good job with the other packages that you
+maintain. Alternatively you may ask the help of other people in order to
+catch up the backlog of bugs that you have (you can ask for help on
+&email-debian-qa; or &email-debian-devel;).
 
       <sect>Retiring Gracefully
        <p>
@@ -320,7 +402,7 @@ 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-private and &email-debian-devel-announce;.  There are
+&email-debian-private; and &email-debian-devel-announce;.  There are
 other mailing lists are 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.
@@ -332,12 +414,17 @@ 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.
        <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-debian-list-archives;">.
+id="&url-lists-archives;">.
 
 
       <sect id="server-machines">Debian servers
@@ -348,18 +435,14 @@ are and what they do.
        <p>
 If you have a problem with the operation of Debian server, and you
 think that the system operators need to be notified of this problem,
-please find the contact address for the particular role at <url
-id="&url-debian-contacts;">.  If you have a non-operating problems
+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.),
 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
        <p>
-The master server, <tt>master.debian.org</tt>, holds the canonical copy
-of the Debian archive (excluding the non-U.S. packages). Generally,
-package uploads go to this server; see <ref id="upload">. 
-       <p>
 <tt>master.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.
@@ -374,13 +457,21 @@ in the clear.
        <p>
 If you find a problem with <tt>master.debian.org</tt> such as disk
 full, suspicious activity, or whatever, send an email to
-&email-debian-admin;.  Problems with the Debian FTP archive generally
-need to be reported as 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">.
+&email-debian-admin;.
 
-      <sect1 id="servers-www">The WWW servers
+      <sect1 id="servers-ftp-master">The ftp-master server
+       <p>
+The ftp-master server, <tt>ftp-master.debian.org</tt> (or
+<tt>auric.debian.org</tt>), holds the canonical copy of the Debian
+archive (excluding the non-U.S. packages). Generally, package uploads
+go to this server; see <ref id="upload">.
+       <p>
+Problems with the Debian FTP archive generally need to be reported as
+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
        <p>
 The main web server, <tt>www.debian.org</tt>, is also known as
 <tt>va.debian.org</tt>.  All developers are given accounts on this
@@ -389,23 +480,19 @@ machine.
 If you have some Debian-specific information which you want to serve
 up on the web, you can do do this by putting material in the
 <file>public_html</file> directory under your home directory.  You can
-do this on either <tt>va.debian.org</tt> or
-<tt>master.debian.org</tt>.  Any material you put in those areas are
-accessible via the URLs
-<tt>http://www.debian.org/~<var>user-id</var>/</tt> and
-<tt>http://master.debian.org/~<var>user-id</var>/</tt>, respectively.
-Generally, you'll want to use <tt>va</tt>, for the
-<tt>www.debian.org</tt> address, although in some cases you may need
-to put it on <tt>master</tt>.  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.
+do this on <tt>va.debian.org</tt>. Any material you put in those areas
+are accessible via the URL
+<tt>http://www.debian.org/~<var>user-id</var>/</tt>.
+If necessary, you can use other Debian machines for this; the procedure
+is analogous to the above. 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.
        <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
-else has already reported the problem on the <url
-id="&url-bts;db/pa/lwww.debian.org.html" name="Bug Tracking System">.
+else has already reported the problem on the
+<url id="http://bugs.debian.org/www.debian.org" name="Bug Tracking System">.
 
 
       <sect1 id="servers-cvs">The CVS server
@@ -446,10 +533,6 @@ your own mirror, either for internal or public access.
 Note that mirrors are generally run by third-parties who are
 interested in helping Debian.  As such, developers generally do not
 have accounts on these machines.
-       <p>
-Please do not mirror off of <tt>master.debian.org</tt>.  This host
-already has too much load.  Check the sites above for information, or
-email <email>debian-devel@lists.debian.org</email>.
 
 
       <sect id="other-machines">Other Debian Machines
@@ -754,17 +837,13 @@ point to the appropriate release directories.
        <p>
 If you want to create a new package for the Debian distribution, you
 should first check the <url id="&url-wnpp;" name="Work-Needing and
-Prospective Packages (WNPP)"> list.  Checking the WNPP ensures that no
-one is already working on packaging that software, and that effort is
-not duplicated. Assuming no one else is already working on your
-prospective package, you must then send a short email to
-&email-debian-devel; describing your plan to create a new package.
-You should set the subject of the email to ``intent to package
-<var>foo</var>'', substituting the name of the new package for
-<var>foo</var>.
-       <p>
-There are a number of reasons why we ask maintainers to follow these
-steps:
+Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that
+no one is already working on packaging that software, and that effort is
+not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for
+more information.
+       <p>
+There are a number of reasons why we ask maintainers to announce their
+intentions:
          <list compact>
            <item>
 It helps the (potentially new) maintainer to tap into the experience
@@ -772,15 +851,11 @@ of people on the list, and lets them know if any one else is working
 on it already.
            <item>
 It lets other people thinking about working on the package know that
-there already is a volunteer, and efforts may be shared.  The ``intent
-to package'' message to &email-debian-devel@; will be picked up the
-the WNPP maintainer, and your intention will be published in
-subsequent versions of the WNPP document.
+there already is a volunteer, and efforts may be shared.
            <item>
 It lets the rest of the maintainers know more about the package than
-the one line description and the changelog entry ``Initial version''
-that generally gets posted to <tt>debian-devel-changes</tt> by
-default.
+the one line description and the usual changelog entry ``Initial release''
+that gets posted to <tt>debian-devel-changes</tt>.
            <item>
 It is helpful to the people who live off unstable (and form our first
 line of testers); we should encourage these people.
@@ -825,12 +900,16 @@ put `stable unstable' in the <file>changelog</file>'s
 <tt>Distribution</tt> field.  Or, if Debian has been frozen, and you
 want to get a bug-fix release into <em>frozen</em>, you would set the
 distribution to `frozen unstable'.  (See <ref id="upload-frozen"> for
-more information on when to upload to <em>frozen</em>.)  Note that
-setting the distribution to `stable' means that the package will be
-placed into the <tt>proposed-updates</tt> directory of the Debian
-archive for further testing before it is actually included in
-<em>stable</em>.  Also note that it never makes sense to combine the
-<em>experimental</em> distribution with anything else.
+more information on when to upload to <em>frozen</em>.)  Note that it
+never makes sense to combine the <em>experimental</em> distribution with
+anything else.  Also note that setting the distribution to `stable' means
+that the package will be placed into the <tt>proposed-updates</tt>
+directory of the Debian archive for further testing before it is actually
+included in <em>stable</em>. The Release Team (which can be reached at
+&email-debian-release;) will decide if your package can be included in
+stable, therefore if your changelog entry is not clear enough, you may
+want to explain them why you uploaded your package to stable by sending 
+them a short explication.
          <p>
 The first time a version is uploaded which corresponds to a particular
 upstream version the original source tar file should be uploaded and
@@ -925,19 +1004,17 @@ Remove the package, then reinstall it.
            </list>
 
 
-       <sect1 id="upload-master">Uploading to <tt>master</tt>
+       <sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>
          <p>
 To upload a package, you need a personal account on
-<ftpsite>master.debian.org</ftpsite>.  All maintainers should already
-have this account, see <ref id="servers-master">.  You can use either
-<prgn>scp</prgn> or <prgn>ftp</prgn> to transfer the files.  In either
-case, the files need to be placed into
-<ftppath>&master-upload-dir</ftppath>.  (You cannot upload to Incoming
-on master using anonymous FTP -- you must use your user-name and
-password.)
+<ftpsite>ftp-master.debian.org</ftpsite>, which you should have as an
+official maintainer. If you use <prgn>scp</prgn> or <prgn>rsync</prgn>
+to transfer the files, place them into <ftppath>&us-upload-dir;</ftppath>;
+if you use anonymous FTP to upload, place them into
+<ftppath>/pub/UploadQueue/</ftppath>.
           <p>
 <em>Note:</em> Do not upload packages containing software that is
-export-controlled by the United States government to <tt>master</tt>,
+export-controlled by the United States government to <tt>ftp-master</tt>,
 nor to the overseas upload queues on <tt>chiark</tt> or
 <tt>erlangen</tt>.  This prohibition covers almost all cryptographic
 software, and even sometimes software that contains ``hooks'' to
@@ -949,36 +1026,44 @@ message to &email-debian-devel; and ask.
          <p>
 You may also find the Debian package <package>dupload</package> useful
 when uploading packages.  This handy program is distributed with
-defaults for uploading via <prgn>ftp</prgn> to <tt>master</tt>,
+defaults for uploading via <prgn>ftp</prgn> to <tt>ftp-master</tt>,
 <tt>chiark</tt>, and <tt>erlangen</tt>.  It can also be configured to
-use <prgn>ssh</prgn>.  See <manref name="dupload" section="1"> and
-<manref name="dupload" section="5"> for more information.
-
+use <prgn>ssh</prgn> or <prgn>rsync</prgn>.  See <manref name="dupload"
+section="1"> and <manref name="dupload" section="5"> for more information.
+         <p>
+After uploading your package, you can check how dinstall will
+process it by running dinstall on your changes file:
+<example>/org/ftp.debian.org/scripts/dinstall/dinstall -n foo.changes</example>
 
-       <sect1 id="upload-non-us">Uploading to <tt>pandora</tt> (non-us)
+       <sect1 id="upload-non-us">Uploading to <tt>non-us</tt> (pandora)
          <p>
 As discussed above, export controlled software should not be uploaded
-to <tt>master</tt>.  Instead, use non-anonymous FTP or
-<prgn>scp</prgn> to copy the package to
-<ftpsite>pandora.debian.org</ftpsite>, placing the files in
-<ftppath>&non-us-upload-dir</ftppath>.  By default, you can use your
-same account which works on <tt>master</tt>.
+to <tt>ftp-master</tt>.  Instead, use <prgn>scp</prgn> or non-anonymous
+FTP to copy the package to <ftpsite>non-us.debian.org</ftpsite>, placing
+the files in <ftppath>&non-us-upload-dir;</ftppath>. By default, you can
+use the same account/password that works on <tt>ftp-master</tt>.
          <p>
 The program <prgn>dupload</prgn> comes with support for uploading to
-<tt>pandora</tt>; please refer to the documentation that comes with
+<tt>non-us</tt>; please refer to the documentation that comes with
 the program for details.
-
+         <p>
+Similar to the way it's done on <tt>ftp-master</tt>, you can check your
+upload with:
+<example>
+/org/non-us.debian.org/scripts/dinstall/dinstall -n foo.changes
+</example>
+      
        <sect1>Uploads via <tt>chiark</tt>
          <p>
-If you have a slow network connection to <tt>master</tt>, there are
+If you have a slow network connection to <tt>ftp-master</tt>, there are
 alternatives.  One is to upload files to <tt>Incoming</tt> via a
 upload queue in Europe on <tt>chiark</tt>. For details connect to
 <url id="&url-chiark-readme;">.
          <p>
 <em>Note:</em> Do not upload packages containing software that is
 export-controlled by the United States government to the queue on
-<tt>chiark</tt>.  Since this upload queue goes to <tt>master</tt>, the
-prescription found in <ref id="upload-master"> applies here as well.
+<tt>chiark</tt>.  Since this upload queue goes to <tt>ftp-master</tt>, the
+prescription found in <ref id="upload-ftp-master"> applies here as well.
          <p>
 The program <prgn>dupload</prgn> comes with support for uploading to
 <tt>chiark</tt>; please refer to the documentation that comes with the
@@ -991,25 +1076,25 @@ Another upload queue is available in Germany: just upload the files
 via anonymous FTP to <url id="&url-upload-erlangen;">.
          <p>
 The upload must be a complete Debian upload, as you would put it into
-<tt>master</tt>'s <tt>Incoming</tt>, i.e., a <tt>.changes</tt> files
+<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
-their way to <tt>master</tt> via the queue. Please also make sure that
+their way to <tt>ftp-master</tt> via the 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
-replies, just as on <tt>master</tt>.
+replies, just as on <tt>ftp-master</tt>.
          <p>
 There's no need to move your files into a second directory after the
 upload as on <tt>chiark</tt>. And, in any case, you should get some
 mail reply from the queue daemon what happened to your
-upload. Hopefully it should have been moved to <tt>master</tt>, but in
+upload. Hopefully it should have been moved to <tt>ftp-master</tt>, but in
 case of errors you're notified, too.
          <p>
 <em>Note:</em> Do not upload packages containing software that is
 export-controlled by the United States government to the queue on
-<tt>erlangen</tt>.  Since this upload queue goes to <tt>master</tt>, the
-prescription found in <ref id="upload-master"> applies here as well.
+<tt>erlangen</tt>.  Since this upload queue goes to <tt>ftp-master</tt>, the
+prescription found in <ref id="upload-ftp-master"> applies here as well.
          <p>
 The program <prgn>dupload</prgn> comes with support for uploading to
 <tt>erlangen</tt>; please refer to the documentation that comes with
@@ -1019,7 +1104,7 @@ the program for details.
        <sect1>Other Upload Queues
          <p>
 Another upload queue is available which is based in the US, and is a
-good backup when there are problems reaching <tt>master</tt>.  You can
+good backup when there are problems reaching <tt>ftp-master</tt>.  You can
 upload files, just as in <tt>erlangen</tt>, to <url
 id="&url-upload-samosa;">.
          <p>
@@ -1031,22 +1116,25 @@ anonymous FTP to <url id="&url-upload-jp;">.
       <sect id="upload-announce">Announcing package uploads
        <p>
 When a package is uploaded an announcement should be posted to one of
-the ``debian-changes'' lists. The announcement should give the
-(source) package name and version number, and a very short summary of
-the changes, in the <em>Subject</em> field, and should contain the
-PGP-signed <tt>.changes</tt> file.  Some additional explanatory text
-may be added before the start of the <tt>.changes</tt> file.
+the ``debian-changes'' lists. This is now done automatically by dinstall
+when it runs (usually once a day), you just need to use a recent
+<package>dpkg-dev</package> (&gt;= 1.4.1.2). Before that, 
+<prgn>dupload</prgn> was used to send those announcements, please make
+sure that you configured your <prgn>dupload</prgn> to no more send those
+announcements (check its documentation and look for dinstall_runs). The
+mail generated by dinstall will contain the PGP/GPG signed .changes files
+that you uploaded with your package.
        <p>
 If a package is released with the <tt>Distribution:</tt> set to
 `stable', the announcement is sent to &email-debian-changes;.  If a
 package is released with <tt>Distribution:</tt> set to `unstable',
-`experimental', or `frozen' (when present), the announcement should be
+`experimental', or `frozen' (when present), the announcement will be
 posted to &email-debian-devel-changes; instead.
        <p>
 On occasion, it is necessary to upload a package to both the
 <em>stable</em> and <em>unstable</em> distributions; this is done by
 putting both distributions in the <tt>Distribution:</tt> line.  In
-such a case the upload announcement should go to both of the above
+such a case the upload announcement will go to both of the above
 mailing lists.
        <p>
 The <prgn>dupload</prgn> program is clever enough to determine for itself
@@ -1621,27 +1709,20 @@ that package, and the package has moved into the archive, file a bug
 against <tt>ftp.debian.org</tt> asking to remove the package with the
 obsolete name.
 
-
-
       <sect id="orphaning">Orphaning a package
        <p>
-If you can no longer maintain a package, then you should set the
-package maintainer to <tt>Debian QA Group
-&lt;debian-qa@lists.debian.org&gt;</tt> and email &email-wnpp;
-indicating that the package is now orphaned.  If the package is
-especially crucial to Debian, you should instead email
-&email-debian-devel; asking for a new maintainer.
-
+If you can no longer maintain a package, you need to inform the others
+about that, and see that the package is marked as orphaned. Read
+instructions on the <url id="&url-wnpp;" name="WNPP web pages"> for more
+information.
 
       <sect id="adopting">Adopting a package
        <p>
-Periodically, a listing of packages in need of new maintainers will be
-sent to &email-debian-devel list. This list is also available at in
-the Work-Needing and Prospective Packages document (WNPP), <url
-id="&url-wnpp;">.  If you wish to take over maintenance of any of the
-packages listed in the WNPP, or if you can no longer maintain a
-packages you have, or you simply want to know if any one is working on
-a new package, send a message to &email-wnpp;.
+A list of packages in need of a new maintainer is available at in the
+<url name="Work-Needing and Prospective Packages list (WNPP)"
+id="&url-wnpp;">. If you wish to take over maintenance of any of the
+packages listed in the WNPP, please take a look at the aforementioned
+page for more information.
        <p>
 It is not OK to simply take over a package that you feel is neglected
 -- that would be package hijacking.  You can, of course, contact the
@@ -1732,15 +1813,15 @@ in your <file>debian/changelog</file> file:
 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 safety to prevent operator dismemberment, closes: bug#98765,
+    bug#98713, #98714.
+  * Added manpage. Closes: #98725.
 </example>
 
 Technically speaking, the following Perl regular expression is what is
 used:
 <example>
-  /closes:\s*(bug)?\#\d+(,\s*(bug)?\#\d+)*/gi
+  /closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig
 </example>
 
 The author prefers the <tt>(closes: Bug#<var>XXX</var>)</tt> syntax,