X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=developers-reference.sgml;h=e793cda7be86a5523e26fb9edabe546fa7ca8694;hb=d17416fdfdea7cc9a962f4b6cc7913477a863908;hp=a0afa47a69bc88d4dc40cab5d7dd670034e68efb;hpb=265684fff23cdf82b2679ab4e37844c7e1c16047;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index a0afa47..e793cda 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.212 $">
+  <!ENTITY cvs-rev "$Revision: 1.218 $">
   <!-- 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>
@@ -1404,7 +1403,7 @@ indefinitely) and news items in the "latest news" section.
 	<p>
 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>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
@@ -1478,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>
@@ -1947,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
@@ -2314,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.
@@ -3072,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
@@ -3096,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>
@@ -3313,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">