- Sec "The Package Tracking System": filled with content from

  Francesco Paolo Lovergine. Heavily updated by myself.
- New Section "Managing sponsored packages" contributed by
  Francesco Paolo Lovergine. Slightly updated by myself.

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1676 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index ed436e4fbfc0ce71742e7f9b7ca82d9ea8b01f05..afee0a3644c6e2fbe83b6b86ddc2e92be41a97bb 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -83,6 +83,10 @@ developers-reference (3.0) unstable; urgency=low
       be upset by a NMU.
     - Stubbed in new Section "Collaborative maintenance".
     - Stubbed in new Section "The Package Tracking System".
       be upset by a NMU.
     - Stubbed in new Section "Collaborative maintenance".
     - Stubbed in new Section "The Package Tracking System".

+    - Sec "The Package Tracking System": filled with content from
+      Francesco Paolo Lovergine. Heavily updated by myself.
+    - New Section "Managing sponsored packages" contributed by
+      Francesco Paolo Lovergine. Slightly updated by myself.

 
   * Antoine Hulin:
     - update French translation
 
   * Antoine Hulin:
     - update French translation

diff --git a/developers-reference.sgml b/developers-reference.sgml
index ed83ffddd6fca1d5d0f54c8ce328927f2bb79ce9..1fdd1801eabc9deaf3c01b6e6515f66238f48d33 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.102 $">
+  <!entity cvs-rev "$Revision: 1.103 $">

   <!-- 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 -->
   <!--


@@ -1051,10 +1051,157 @@ package for the alpha architecture. Each time the package has been
 recompiled on most of the architectures.
 
     <sect id="pkg-tracking-system">The Package Tracking System
 recompiled on most of the architectures.
 
     <sect id="pkg-tracking-system">The Package Tracking System

-      <p>
-&FIXME; Include some documentation of the PTS. Explain how to use the
-keyword mechanism and what they are for. Explain how to setup an
-automatic forward of cvs commits.
+       <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 than 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
+you want to receive.
+       <p>
+By default you will get :
+<taglist>
+    <tag><tt>bts</tt>
+    <item>
+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.
+    
+    <tag><tt>upload-source</tt>
+    <item>
+The confirmation mail 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).
+
+    <tag><tt>default</tt>
+    <item>
+Any non-automatic mail sent to the PTS by people who wanted to
+contact the subscribers of the package.
+
+    <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 testing, ...).
+</taglist>
+       <p>
+You can also decide to receive some more 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).
+
+    <tag><tt>cvs</tt>
+    <item>
+CVS commits if the maintainer has setup a system to forward commit
+notification to the PTS.
+</taglist>
+
+       <sect1 id="pts-commands">The PTS email interface
+       <p>
+You can control your subscription(s) to the PTS by sending
+various commands to <email>pts@qa.debian.org</email>.
+
+<taglist>
+
+<tag><tt>subscribe &lt;srcpackage&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,
+  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>
+<item>
+  Removes a previous subscription to the source package <var>srcpackage</var>
+  using the specified email address or the sender address if the second
+  argument is left out. 
+
+<tag><tt>which [&lt;email&gt;]</tt>
+<item>
+  Lists all subscriptions for the sender or the email address optionally 
+  specified.
+
+<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 :
+  <list>
+  <item><tt>bts</tt> : mails coming from the Debian Bug Tracking System
+  <item><tt>bts-control</tt> : reply to mails sent to
+        <email>control@bugs.debian.org</email>
+  <item><tt>summary</tt> : automatic summary mails about the state of a package
+  <item><tt>cvs</tt> : notification of cvs commits
+  <item><tt>upload-source</tt> : announce of a new source upload that
+        has been accepted
+  <item><tt>upload-binary</tt> : announce of a new binary-only upload (porting)
+  <item><tt>katie-other</tt> : other mails from ftpmasters
+        (override disparity, etc.)
+  <item><tt>default</tt> : all the other mails (those which aren't "automatic")
+  </list>
+
+<tag><tt>keyword &lt;srcpackage&gt; [&lt;email&gt;]</tt>
+<item>
+  Same as 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>
+<item>
+  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>
+<item>
+  Same as previous item but overrides the keywords list for the
+  indicated source package.
+  
+<tag><tt>quit | thanks | --</tt>
+<item>
+  Stops processing commands. All following lines are ignored by
+  the bot.
+</taglist>
+
+       <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
+have special headers appended to let you filter them in a special
+mailbox 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>
+Here is an example of added headers for a source upload notification
+on the <package>dpkg</package> package :
+<example>
+X-Loop: dpkg@&pts-host;
+X-PTS-Package: dpkg
+X-PTS-Keyword: upload-source
+X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org
+</example>
+
+       <sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS
+       <p>
+If you use a publically 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
+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.

 
 
    <chapt id="pkgs">Managing Packages
 
 
    <chapt id="pkgs">Managing Packages


@@ -2477,6 +2624,40 @@ If you are an application manager for a prospective developer, you can also
 be their sponsor. That way you can also verify how the applicant is
 handling the 'Tasks and Skills' part of their application.
 
 be their sponsor. That way you can also verify how the applicant is
 handling the 'Tasks and Skills' part of their application.
 

+      <sect1>Managing sponsored packages
+        <p>
+By uploading a sponsored package to Debian, you are certifying that
+the package meets minimum Debian standards.  That implies that you
+must build and test the package on your own system before uploading.
+       <p>
+You can not simply upload a binary <tt>.deb</tt> from the sponsoree. In
+theory, you should only ask only for the diff file, and the location of the
+original source tarball, and then you should download the source and apply
+the diff yourself. In practice, you may want to use the source package
+built by your sponsoree. In that case you have to check that he hasn't
+altered the upstream files in the <tt>.orig.tar.gz</tt> file that he's
+providing.
+       <p>
+Do not be afraid to write the sponsoree back and point out changes
+that need to be made.  It often takes several rounds of back-and-forth
+email before the package is in acceptable shape.  Being a sponsor
+means being a mentor.
+       <p>
+Once the package meets Debian standards, build the package with
+<example>dpkg-buildpackage -us -uc</example> and sign it
+with <example>debsign -m your@email.com <var>changes file</var></example>
+before uploading it to the incoming directory.
+       <p>
+The Maintainer field of the <tt>control</tt> file and the
+<tt>changelog</tt> should list the person who did the packaging, i.e. the
+sponsoree. The sponsoree will therefore get all the BTS mail about the
+package. 
+       <p>
+If you prefer to leave a more evident trace of your sponsorship job, you
+can add a line stating it in the most recent changelog entry.
+       <p>
+You are encouraged to keep tabs on the package you sponsor using 
+<ref id="pkg-tracking-system">.

 
       <sect1>Advocating new developers
        <p>
 
       <sect1>Advocating new developers
        <p>