X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=developers-reference.sgml;h=4d4a87b75faa281d0ef999e7fa970dc27b8c4e23;hb=e94546c373483de053d007056216645ef48117c9;hp=601c837c561db2f3d1e9070fbcef7a1a454ed750;hpb=ff347fa9d4d749498487d93df89557e4427c5e35;p=developers-reference.git

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 601c837..4d4a87b 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.213 $">
+  <!ENTITY cvs-rev "$Revision: 1.217 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -487,8 +487,8 @@ 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
-<url name="Alioth" id="&url-alioth;"> is more appropriate.
+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"
@@ -1403,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
@@ -1477,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>
@@ -1946,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
@@ -2313,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.
@@ -3071,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
@@ -3095,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>
@@ -3312,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">