X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=980727a95d9314203cde41f1e1eaa742646f3cd4;hb=1ddd594cc8648ede682512743a98f1a58ce129b7;hp=4d2bd169bb9ef2bb8de570891096f1950b070365;hpb=3b9bfcd0ded72361b26618016e5d438d60118ef9;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 4d2bd16..980727a 100644
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.210 $">
+  <!ENTITY cvs-rev "$Revision: 1.219 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -142,7 +142,7 @@ name="New Maintainer's Corner">.  It describes exactly the
 preparations you have to do before you can register to become a Debian
 developer.
 
-For example, before you apply, you have to to read the <url
+For example, before you apply, you have to read the <url
 id="&url-social-contract;" name="Debian Social Contract">.
 Registering as a developer means that you agree with and pledge to
 uphold the Debian Social Contract; it is very important that
@@ -418,10 +418,29 @@ 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>.
+Much of the conversation between Debian developers (and users) is managed
+through a wide array of mailing lists we host at
+<tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.
+To find out more on how to subscribe or unsubscribe, how to post and how not
+to post, where to find old posts and how to search them, how to contact the
+list maintainers and see various other information about the mailing lists,
+please read <url id="&url-debian-lists;">. This section will only cover
+aspects of mailing lists that are of particular interest to developers.
+
+	<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>
+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.
 	<p>
-Online archives of mailing lists are available at <url
-id="&url-lists-archives;">.
+Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">
+for more information.
 
 	<sect1 id="core-devel-mailing-lists">Core development mailing lists
 	<p>
@@ -442,40 +461,8 @@ The core Debian mailing lists that developers should use are:
   </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.
-	<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-txt;">
-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>
-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.
-	<p>
-Please read the <url name="code of conduct" id="&url-debian-lists;">
-for more information.
+There are other mailing lists available for a variety of special topics;
+see <url id="http://&lists-host;/"> for a list.
 
 	<sect1 id="mailing-lists-special">Special lists
 	<p>
@@ -494,6 +481,18 @@ 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.
 
+	<sect1 id="mailing-lists-new">Requesting new development-related lists
+	<p>
+Before requesting a mailing list that relates to the development of a
+package (or a small group of related packages), please consider if using
+an alias (via a .forward-aliasname file on master.debian.org, which
+translates into a reasonably nice <var>you-aliasname@debian.org</var>
+address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>
+is more appropriate.
+	<p>
+If you decide that a regular mailing list on lists.debian.org is really what
+you want, go ahead and fill in a request, following <url name="the HOWTO"
+id="&url-debian-lists-new;">.
 
       <sect id="irc-channels">IRC channels
 	<p>
@@ -1221,12 +1220,13 @@ recompiled on most of the architectures.
 
     <sect id="pkg-tracking-system">The Package Tracking System
 	<p>
-The Package Tracking System (PTS) is basically a tool to track by mail
-the activity of a source package. You just have to subscribe
-to a source package to start getting the mails related to it. 
-You get the same mails as the maintainer. Each mail
-sent through the PTS is classified and associated to one of
-the keyword listed below. This will let you select the mails that
+The Package Tracking System (PTS) is an email-based tool to track
+the activity of a source package. This really means that you can
+get the same emails that the package maintainer gets, simply by
+subscribing to the package in the PTS.
+	<p>
+Each email sent through the PTS is classified and associated to one of
+the keywords listed below. This will let you select the mails that
 you want to receive.
 	<p>
 By default you will get:
@@ -1237,46 +1237,48 @@ All the bug reports and following discussions.
 
     <tag><tt>bts-control</tt>
     <item>
-The control mails notifying a status change in one of the bugs.
+The email notifications from <email>control@bugs.debian.org</email>
+about bug report status changes.
     
     <tag><tt>upload-source</tt>
     <item>
-The confirmation mail from <prgn>katie</prgn> when an uploaded source
+The email notification from <prgn>katie</prgn> when an uploaded source
 package is accepted.
 
     <tag><tt>katie-other</tt>
     <item>
-Other warning and error mails from <prgn>katie</prgn> (like the
-override disparity for the section or priority field).
+Other warning and error emails from <prgn>katie</prgn> (such as an
+override disparity for the section and/or the priority field).
 
     <tag><tt>default</tt>
     <item>
-Any non-automatic mail sent to the PTS by people who wanted to
+Any non-automatic email sent to the PTS by people who wanted to
 contact the subscribers of the package. This can be done by sending mail
-to <tt><var>srcpackage</var>@&pts-host;</tt>. In order to prevent spam,
-mails sent to these addresses must contain the header "X-PTS-Approved"
-with a non-empty string.
-
+to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,
+all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>
+header with a non-empty value.
 
     <tag><tt>summary</tt>
     <item>
-In the future, you may receive regular summary mails to keep you
-informed of the package's status (bug statistics, porting overview,
-progression in <em>testing</em>, ...).
+(This is a planned expansion.)
+The regular summary emails about the package's status (bug statistics,
+porting overview, progression in <em>testing</em>, ...).
 </taglist>
+
 	<p>
-You can also decide to receive some more information:
+You can also decide to receive additional information:
 <taglist>
     <tag><tt>upload-binary</tt>
     <item>
-The confirmation mail from <prgn>katie</prgn> when an uploaded binary
-package is accepted (to check that your package is recompiled for all
-architectures).
+The email notification from <prgn>katie</prgn> when an uploaded binary
+package is accepted. In other words, whenever a build daemon or a porter
+uploads your package for another architecture, you can get an email to
+track how your package gets recompiled for all architectures.
 
     <tag><tt>cvs</tt>
     <item>
-CVS commits if the maintainer has setup a system to forward commit
-notification to the PTS.
+CVS commit notifications, if the package has a CVS repository and the
+maintainer has set up forwarding commit notifications to the PTS.
 
     <tag><tt>ddtp</tt>
     <item>
@@ -1291,17 +1293,17 @@ various commands to <email>pts@qa.debian.org</email>.
 
 <taglist>
 
-<tag><tt>subscribe &lt;srcpackage&gt; [&lt;email&gt;]</tt>
+<tag><tt>subscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
 <item>
   Subscribes <var>email</var> to communications related to the source package
-  <var>srcpackage</var>. Sender address is used if the second argument is
-  not present. If <var>srcpackage</var> is not a valid source package,
+  <var>sourcepackage</var>. Sender address is used if the second argument is
+  not present. If <var>sourcepackage</var> is not a valid source package,
   you'll get a warning. However if it's a valid binary package, the PTS
   will subscribe you to the corresponding source package.
 
-<tag><tt>unsubscribe &lt;srcpackage&gt; [&lt;email&gt;]</tt>
+<tag><tt>unsubscribe &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
 <item>
-  Removes a previous subscription to the source package <var>srcpackage</var>
+  Removes a previous subscription to the source package <var>sourcepackage</var>
   using the specified email address or the sender address if the second
   argument is left out. 
 
@@ -1312,10 +1314,9 @@ various commands to <email>pts@qa.debian.org</email>.
 
 <tag><tt>keyword [&lt;email&gt;]</tt>
 <item>
-  Tells you the keywords that you are accepting. Each mail sent through
-  the Package Tracking System is associated to a keyword and you receive
-  only the mails associated to keywords that you are accepting. Here is
-  the list of available keywords:
+  Tells you the keywords that you are accepting.
+  For an explanation of keywords, <qref id="pkg-tracking-system">see
+  above</qref>. Here's a quick summary:
   <list>
   <item><tt>bts</tt>: mails coming from the Debian Bug Tracking System
   <item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;
@@ -1330,9 +1331,9 @@ various commands to <email>pts@qa.debian.org</email>.
   <item><tt>default</tt>: all the other mails (those which aren't "automatic")
   </list>
 
-<tag><tt>keyword &lt;srcpackage&gt; [&lt;email&gt;]</tt>
+<tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;]</tt>
 <item>
-  Same as previous item but for the given source package since
+  Same as the previous item but for the given source package, since
   you may select a different set of keywords for each source package.
 
 <tag><tt>keyword [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
@@ -1340,7 +1341,7 @@ various commands to <email>pts@qa.debian.org</email>.
   Accept (+) or refuse (-) mails associated to the given keyword(s).
   Define the list (=) of accepted keywords.
 
-<tag><tt>keyword &lt;srcpackage&gt; [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
+<tag><tt>keyword &lt;sourcepackage&gt; [&lt;email&gt;] {+|-|=} &lt;list of keywords&gt;</tt>
 <item>
   Same as previous item but overrides the keywords list for the
   indicated source package.
@@ -1354,9 +1355,9 @@ various commands to <email>pts@qa.debian.org</email>.
 	<sect1 id="pts-mail-filtering">Filtering PTS mails
 	<p>
 Once you are subscribed to a package, you will get the mails sent to
-<tt><var>srcpackage</var>@packages.qa.debian.org</tt>. Those mails
+<tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails
 have special headers appended to let you filter them in a special
-mailbox with <prgn>procmail</prgn>. The added headers are
+mailbox (e.g. with <prgn>procmail</prgn>). The added headers are
 <tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and
 <tt>X-Unsubscribe</tt>.
 	<p>
@@ -1373,64 +1374,64 @@ X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
 	<p>
 If you use a publicly accessible CVS repository for maintaining
 your Debian package you may want to forward the commit notification
-to the PTS so that the subscribers (possible co-maintainers) can
+to the PTS so that the subscribers (and possible co-maintainers) can
 closely follow the package's evolution.
 	<p>
-It's very easy to setup. Once your CVS repository generates commit
-notifications, you just have to make sure it sends a copy of those mails
-to <tt><var>srcpackage</var>_cvs@&pts-host;</tt>. Only people who
-accepts the <em>cvs</em> keyword will receive the notifications.
+Once you set up the CVS repository to generate commit notifications,
+you just have to make sure it sends a copy of those mails
+to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people
+who accept the <em>cvs</em> keyword will receive these notifications.
 
 	<sect1 id="pts-web">The PTS web interface
 	<p>
-The PTS has been extended with a web interface that puts together
-many information about each source package. It features many useful
+The PTS has a web interface at <url id="http://&pts-host;/"> that puts
+together a lot of information about each source package. It features many useful
 links (BTS, QA stats, contact information, DDTP translation status,
-buildd logs) and gathers many more information from various places
+buildd logs) and gathers much more information from various places
 (30 latest changelog entries, testing status, ...). It's a very useful
 tool if you want to know what's going on with a specific source
-package. Furthermore there's a form that let you easily subscribe to
-the mail service offered by the PTS.
+package. Furthermore there's a form that allows easy subscription to
+the PTS via email.
 	<p>
 You can jump directly to the web page concerning a specific source package
-with an url like <tt>http://&pts-host;/<var>srcpackage</var></tt>. Otherwise
-you can go through the <url id="http://&pts-host;" name="main page">.
+with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.
 	<p>
 This web interface has been designed like a portal for the development of
-packages: you can add custom content on the pages of your packages. You can
-add "static information" (news item that are meant to stay available
+packages: you can add custom content on your packages' pages. You can
+add "static information" (news items that are meant to stay available
 indefinitely) and news items in the "latest news" section.
 	<p>
-Static news can be used to indicate:
+Static news items can be used to indicate:
 <list>
-<item>the availability of a project hosted on alioth.debian.org for co-maintaining the package
-<item>a link to the upstream website
-<item>a link to the upstream bugtracker
+<item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package
+<item>a link to the upstream web site
+<item>a link to the upstream bug tracker
 <item>the existence of an IRC channel dedicated to the software
 <item>any other available resource that could be useful in the maintenance of the package
 </list>
-Usual news item may be used to announce that:
+Usual news items may be used to announce that:
 <list>
-<item>beta packages are available for test
+<item>beta packages are available for testing
 <item>final packages are expected for next week
 <item>the packaging is about to be redone from scratch
 <item>backports are available
-<item>the maintainer is on vacation (if he wishes to publish this information)
+<item>the maintainer is on vacation (if they wish to publish this information)
 <item>a NMU is being worked on
 <item>something important will affect the package
 </list>
 	<p>
-Both kind of news are generated in a similar manner: you just have to send a mail
-either to <email>pts-static-news@qa.debian.org</email> or to
-<email>pts-news@qa.debian.org</email>. The mail should indicate which package is
-concerned by the news by giving the name of the source package in a
+Both kind of news are generated in a similar manner: you just have to send
+an email either to <email>pts-static-news@qa.debian.org</email> or to
+<email>pts-news@qa.debian.org</email>. The mail should indicate which
+package is concerned by having the name of the source package in a
 <tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the
-BTS reports). If an URL is available in the <tt>X-PTS-Url</tt> mail header or in
+BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in
 the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead
 of a complete news item.
 	<p>
-Some examples of valid mails used to generate news item in the PTS are following. The first one
-adds a link to the cvsweb interface of debian-cd in the "Static information" section.
+Here are a few examples of valid mails used to generate news items in
+the PTS. The first one adds a link to the cvsweb interface of debian-cd
+in the "Static information" section:
 <example>
 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
 To: pts-static-news@qa.debian.org
@@ -1439,9 +1440,10 @@ Subject: Browse debian-cd CVS repository with cvsweb
 Package: debian-cd
 Url: http://cvs.debian.org/debian-cd/
 </example>
-The second one is an announce sent to a mailing list which is also sent
+	<p>
+The second one is an announcement sent to a mailing list which is also sent
 to the PTS so that it is published on the PTS web page of the package. Note the
-use of the BCC field to avoid answers sent to the PTS by mistake ...
+use of the BCC field to avoid answers sent to the PTS by mistake.
 <example>
 From: Raphael Hertzog &lt;hertzog@debian.org&gt;
 To: debian-gtk-gnome@lists.debian.org
@@ -1449,17 +1451,17 @@ Bcc: pts-news@qa.debian.org
 Subject: Galeon 2.0 backported for woody
 X-PTS-Package: galeon
 
-Hello gnomers !
+Hello gnomers!
 
 I'm glad to announce that galeon has been backported for woody. You'll find
 everything here:
 ...
 </example>
 	<p>
-Think twice before adding a news to the PTS because you won't be able to
-remove it later and you wan't be able to edit it either. The only thing that you
-can do is send a second news that will deprecate the information contained in
-the first news.
+Think twice before adding a news item to the PTS because you won't be able
+to remove it later and you wan't be able to edit it either. The only thing
+that you can do is send a second news item that will deprecate the
+information contained in the previous one.
 
     <sect id="ddpo">Developer's packages overview
 	<p>
@@ -1475,6 +1477,21 @@ 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.
 
+    <sect id="alioth">Debian *Forge: Alioth
+	<p>
+Alioth is a fairly new Debian service, based on a slightly modified version
+of the GForge software (which evolved from SourceForge). This software
+offers developers access to easy-to-use tools such as bug trackers, patch
+manager, project/task managers, file hosting services, mailing lists, CVS
+repositories etc. All these tools are managed via a web interface.
+	<p>
+It is intended to provide facilities to free software projects backed or led
+by Debian, facilitate contributions from external developers to projects
+started by Debian, and help projects whose goals are the promotion of Debian
+or its derivatives.
+	<p>
+For more information please visit <url id="&url-alioth;">.
+
 
    <chapt id="pkgs">Managing Packages
 	<p>
@@ -1944,8 +1961,8 @@ reorder them, and how to process and close them.
 	<p>
 The bug tracking system's features interesting to developers are described
 in the <url id="&url-bts-devel;" name="BTS documentation for developers">.
-This includes closing bugs, sending followup messages, assigning severities,
-tags, marking bugs as forwarded and other issues.
+This includes closing bugs, sending followup messages, assigning severities
+and tags, marking bugs as forwarded and other issues.
 	<p>
 Operations such as reassigning bugs to other packages, merging separate
 bug reports about the same issue, or reopening bugs when they are
@@ -2311,17 +2328,24 @@ When packaging the fix, keep the following points in mind:
     <file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for
     testing this is <tt>testing-security</tt>, and for the previous
     stable release, this is <tt>oldstable-security</tt>. Do not target
-    <var>distribution</var>-proposed-updates!
+    <var>distribution</var>-proposed-updates or <tt>stable</tt>!
 
     <item>Make descriptive, meaningful changelog entries.  Others will
     rely on them to determine whether a particular bug was fixed.
-    Whenever possible, include an external reference, preferably a CVE
-    identifier, so that it can be cross-referenced.
+    Always include an external reference, preferably a CVE
+    identifier, so that it can be cross-referenced.  Include the same
+    information in the changelog for unstable, so that it is clear that
+    the same bug was fixed, as this is very helpful when verifying
+    that the bug is fixed in the next stable release.  If a CVE
+    identifier has not yet been assigned, the security team will
+    request one so that it can be included in the package and in the advisory.
 
     <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 <em>testing</em>, there must be
+    --compare-versions</tt>.  Be careful not to re-use a version
+    number that you have already used for a previous upload.  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.
@@ -3069,7 +3093,8 @@ the <tt>Maintainer</tt> field of the <file>debian/control</file> file.
 Co-maintainers are all the other maintainers.</p>
         <p>
 In its most basic form, the process of adding a new co-maintainer is
-quite easy:<list>
+quite easy:
+<list>
             <item>
               <p>
 Setup the co-maintainer with access to the sources you build the
@@ -3093,10 +3118,12 @@ Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers
 should subscribe themselves to the appropriate source package.</p>
             </item>
           </list></p>
+	<p>
+Collaborative maintenance can often be further eased with the use of
+tools on Alioth (see <ref id="alioth">).
       </sect>
 
 
-
   <chapt id="best-pkging-practices">
     <heading>Best Packaging Practices</heading>
     <p>
@@ -3233,7 +3260,7 @@ this using an hand-crafted <file>debian/rules</file> file.
         <p>
 The following practices are relevant to the
 <file>debian/control</file> file.  They supplement the <url
-id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+id="&url-debian-policy;ch-binary.html#s-descriptions"
 name="Policy on package descriptions">.
         <p>
 The description of the package, as defined by the corresponding field
@@ -3310,9 +3337,9 @@ or, if the package name itself is a plural (such as
 
 <example><var>package-name</var> are <var>synopsis</var>.</example>
 
-This way of forming a sentance from the package name and synopsis
+This way of forming a sentence from the package name and synopsis
 should be considered as a heuristic and not a strict rule.  There are
-some cases where it doesn't make sense to try to form a sentance.
+some cases where it doesn't make sense to try to form a sentence.
         </sect1>
 
 	<sect1 id="bpp-pkg-desc">