Per Bartosz Fe?ski aka fEnIo <fenio@o2.pl>: typo "to to" --> "to"

[developers-reference.git] / developers-reference.sgml

diff --git a/developers-reference.sgml b/developers-reference.sgml
index a0afa47a69bc88d4dc40cab5d7dd670034e68efb..e793cda7be86a5523e26fb9edabe546fa7ca8694 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!ENTITY % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
   <!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 -->
   <!--
   <!-- 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.
 
 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
 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>
 
       <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>
        <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>
 
        <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>
   </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>
 
        <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.
 
 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>
 
       <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>
        <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
 <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.
 
 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>
 
    <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">.
        <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
        <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
     <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.
 
     <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
 
     <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.
     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
 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
             <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>
 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>
 
 
       </sect>
 
 

-

   <chapt id="best-pkging-practices">
     <heading>Best Packaging Practices</heading>
     <p>
   <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>
 
 
 <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
 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">
         </sect1>
 
        <sect1 id="bpp-pkg-desc">