<!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 -->
<!--
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 <srcpackage> [<email>]</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 <srcpackage> [<email>]</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 [<email>]</tt>
+<item>
+ Lists all subscriptions for the sender or the email address optionally
+ specified.
+
+<tag><tt>keyword [<email>]</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 <srcpackage> [<email>]</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 [<email>] {+|-|=} <list of keywords></tt>
+<item>
+ Accept (+) or refuse (-) mails associated to the given keyword(s).
+ Define the list (=) of accepted keywords.
+
+<tag><tt>keyword <srcpackage> [<email>] {+|-|=} <list of keywords></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
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>
~ianmdlvl / developers-reference.git / commitdiff