Team-Maintainence documentation; #410159

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

diff --git a/developers-reference.sgml b/developers-reference.sgml
index fd11da662724442e9ddb410b7c477c8ef23eca21..a09903cfd840dcdd2035f96644ebf1d09a5a1873 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -7,7 +7,7 @@
   <!ENTITY % dynamicdata  SYSTEM "dynamic.ent" > %dynamicdata;
 
   <!-- CVS revision of this document -->
-  <!ENTITY cvs-rev "$Revision: 1.324 $">
+  <!ENTITY cvs-rev "$Revision: 1.326 $">
 
   <!-- if you are translating this document, please notate the CVS
        revision of the original developer's reference in cvs-en-rev -->
@@ -3314,7 +3314,8 @@ quite easy:
 Setup the co-maintainer with access to the sources you build the
 package from.  Generally this implies you are using a network-capable
 version control system, such as <prgn>CVS</prgn> or
-<prgn>Subversion</prgn>.</p>
+<prgn>Subversion</prgn>. Alioth (see <ref id="alioth">) provides such
+tools, amongst others.</p>
             </item>
             <item>
               <p>
@@ -3332,9 +3333,32 @@ 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 by the use of
-tools on Alioth (see <ref id="alioth">).
+              <p>
+Another form of collaborative maintenance is team maintenance, which is
+recommended if you maintain several packages with the same group of
+developers. In that case, the Maintainer and Uploaders field of each
+package must be managed with care. It is recommended to choose between
+one of the two following schemes:
+               <enumlist>
+                <item>
+              <p>
+Put the team member mainly responsible for the package in the Maintainer
+field. In the Uploaders, put the mailing list address, and the team members
+who care for the package.
+                </item>
+                <item>
+              <p>
+Put the mailing list address in the Maintainer field. In the Uploaders
+field, put the team members who care for the package.
+In this case, you must make sure the mailing list accept bug reports
+without any human interaction (like moderation for non-subscribers).
+                </item>
+               </enumlist>
+              <p>
+In any case, it is a bad idea to automatically put all team members in
+the Uploaders field. It clutters the Developer's Package Overview listing
+(see <ref id="ddpo">) with packages one doesn't really care for, and
+creates a false sense of good maintenance.
       </sect>
 
     <sect id="testing">
@@ -4476,6 +4500,8 @@ Don't be too verbose. User tend to ignore too long screens.
 because that means that in the classical dialog interface,
 people will need to scroll, and lot of people just don't do that.
        <p>
+The extended description should <strong>never</strong> include a question. 
+       <p>
 For specific rules depending on templates type (string, boolean,
 etc.), please read below.
 
@@ -4528,8 +4554,6 @@ Below are specific instructions for properly writing the Description
     question is rather long (remember that translations are often longer
     than original versions)
 
-<item> The extended description should <strong>not</strong> include a question. 
-
 <item> Again, please avoid referring to specific interface widgets. A common
     mistake for such templates is "if you answer Yes"-type
     constructions.