From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Thu, 9 May 2002 22:24:33 +0000 (+0000)
Subject: - Sec "The Package Tracking System": filled with content from
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=developers-reference.git;a=commitdiff_plain;h=c8b11816a28e1add890c455142591ccb3e2fb3b8

- 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 ed436e4..afee0a3 100644
--- 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".
+    - 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
diff --git a/developers-reference.sgml b/developers-reference.sgml
index ed83ffd..1fdd180 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.102 $">
+  <!entity cvs-rev "$Revision: 1.103 $">
   <!-- 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
-      <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
@@ -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.
 
+      <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>