path: root/english/Bugs/server-request.wml

#use wml::debian::template title="Debian BTS - request server" NOHEADER=yes NOCOPYRIGHT=true

<h1><a name="introduction">Introduction to the bug system request server</a></h1>

<p>There is a mailserver which can send the bug reports and
indices as plain text on request.</p>

<p>To use it you send a mail message to
<a href="mailto:request@bugs.debian.org"><code>request@bugs.debian.org</code></a>.
The <code>Subject</code> of the message is ignored, except
for generating the <code>Subject</code> of the reply.</p>

<p>The body you send should be a series of commands, one per line.
You'll receive a reply which looks like a transcript of your message
being interpreted, with a response to each command. No notifications
are sent to anyone for the commands listed here and the mail isn't
logged anywhere publicly available.</p>

<p>Any text on a line starting with a hash sign <code>#</code> is
ignored; the server will stop processing when it finds a line with
a <a href="#stopprocessing">control terminator</a> (
<code>quit</code>, <code>thank you</code>, or two
hyphens are common examples).  It will also stop if it
encounters too many unrecognised or badly-formatted commands.  If no
commands are successfully handled it will send the help text for the
server.</p>

<h1>Commands available</h1>

<dl>
<dt><code>send</code> <var>bugnumber</var></dt>
<dt><code>send-detail</code> <var>bugnumber</var></dt>
<dd>
Requests the transcript for the bug report in question.
<code>send-detail</code> sends all of the <q>boring</q> messages in the
transcript as well, such as the various auto-acks.
</dd>

<dt><code>index</code> [<code>full</code>]</dt>
<dt><code>index-summary by-package</code></dt>
<dt><code>index-summary by-number</code></dt>
<dd>
Request the full index (with full details, and including done and
forwarded reports), or the summary sorted by package or by number,
respectively.
</dd>

<dt><code>index-maint</code></dt>
<dd>
Requests the index page giving the list of maintainers with bugs (open
and recently-closed) in the tracking system.
</dd>

<dt><code>index maint</code> <var>maintainer</var></dt>
<dd>
Requests the index pages of bugs in the system for the maintainer
<var>maintainer</var>. The search term is an exact match.
The bug index will be sent in a separate message.
</dd>

<dt><code>index-packages</code></dt>
<dd>
Requests the index page giving the list of packages with bugs (open
and recently-closed) in the tracking system.
</dd>

<dt><code>index packages</code> <var>package</var></dt>
<dd>
Requests the index pages of bugs in the system for the package
<var>package</var>.  The search term is an exact match.
The bug index will be sent in a separate message.
</dd>

<dt><code>getinfo</code> <var>filename</var></dt>
<dd>
<p>
Request a file containing information about package(s) and or
maintainer(s) - the files available are:
</p>

  <dl>
  <dt><code>maintainers</code></dt>
  <dd>
  The unified list of packages' maintainers, as used by the tracking
  system.
  This is derived from information in the <code>Packages</code>
  files, override files and pseudo-packages files.
  </dd>
  
  <dt><code>override.</code><var>distribution</var></dt>
  <dt><code>override.</code><var>distribution</var><code>.non-free</code></dt>
  <dt><code>override.</code><var>distribution</var><code>.contrib</code></dt>
  <dt><code>override.experimental</code></dt>
  <dd>
  Information about the priorities and sections of packages and
  overriding values for the maintainers.  This information is used by
  the process which generates the <code>Packages</code> files in the FTP
  archive.  Information is available for each of the main distribution
  trees available, by their codewords.
  </dd>
  
  <dt><code>pseudo-packages.description</code></dt>
  <dt><code>pseudo-packages.maintainers</code></dt>
  <dd>
  List of descriptions and maintainers respectively for pseudo-packages.
  </dd>
  </dl>
</dd>

<dt><code>refcard</code></dt>
<dd>
Requests that the mailservers' reference card be sent in plain ASCII.
</dd>

<dt><a name="user"><code>user</code> <var>address</var></a></dt>
<dd>
Sets <var>address</var> to be the <q>user</q> of all <code>usertag</code>
commands that follow.
</dd>

<dt><a name="usertag"><code>usertag</code> <var>bugnumber</var>
    [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var>
    [ <var>tag</var> ... ]</a></dt>
<dd>
Allows to define tags on a per-user basis. The <code>usertag</code>
command works just like the regular <code>tag</code> command, except
that you get to make up whatever tags you like. By default, the address
in the <code>From:</code> or <code>Reply-To:</code> header of your mail
will be used to set the user of the <code>usertag</code>.
</dd>

<dt><a name="usercategory"><code>usercategory</code>
     <var>category-name</var> [ <code>[hidden]</code> ]</a></dt>
<dd>
<p>
Adds, updates or removes a <code>usercategory</code>. By default the user
category is visible, if the optional argument <code>[hidden]</code>
is specified then it will not be visible, but still be available to be
referenced from other user category definitions.
</p>

<p>
This command is somewhat special, as when adding or updating a user
category it requires a body following immediately after the command. If
the body is empty the user category will get removed instead. The body
is composed of lines starting with any number of spaces. Each category
should start with a line with <code>*</code>, and optionally it can be
followed by several selection lines starting with <code>+</code>. The
complete format is as follows:
</p>

<div>
* <var>category-name-1</var><br />
* <var>Category Title 2</var>
  [ <code>[</code><var>selection-prefix</var><code>]</code> ]<br />
&nbsp;+ <var>Selection Title 1</var> <code>[</code>
        [ <var>order</var><code>:</code> ]
        <var>selection-1</var> <code>]</code><br />
&nbsp;+ <var>Selection Title 2</var> <code>[</code>
        [ <var>order</var><code>:</code> ]
        <var>selection-2</var> <code>]</code><br />
&nbsp;+ <var>Default Selection Title</var> <code>[</code>
        [ <var>order</var>: ] <code>]</code><br />
* <var>category-name-3</var><br />
</div>

<p>
The <var>category-names</var> appearing in the command and in the body
are used to make references between them, to avoid unnecessary inlining.
The <var>Category Titles</var> are used in the package report summary.
</p>

<p>
The optional <var>selection-prefix</var> is prefixed to every
<var>selection</var> on each entry in the category section. The first
<var>selection</var> which matches gets the bug shown under it. The
optional <var>order</var> parameter specifies the position when showing
the selected entries, this is useful when using a match that selects a
superset of the previous ones but that needs to be shown before them.
</p>

<p>
The <var>category-name</var> <code>normal</code> has the special meaning
of being the default view, so by replacing it with a different user category
for the <var>pkgname</var>@packages.debian.org user one can change the
default classification for a package.
</p>

<p>
Example usage:
</p>

<pre>
    usercategory dpkg-program [hidden]
     * Program
       + dpkg-deb [tag=dpkg-deb]
       + dpkg-query [tag=dpkg-query]
       + dselect [package=dselect]

    usercategory new-status [hidden]
     * Status [pending=]
       + Outstanding with Patch Available [0:pending+tag=patch]
       + Outstanding and Confirmed [1:pending+tag=confirmed]
       + Outstanding and More Information Needed [pending+tag=moreinfo]
       + Outstanding and Forwarded [pending+tag=forwarded]
       + Outstanding but Will Not Fix [pending+tag=wontfix]
       + Outstanding and Unclassified [2:pending]
       + From other Branch [absent]
       + Pending Upload [pending-fixed]
       + Fixed in NMU [fixed]
       + Resolved [done]
       + Unknown Pending Status []

    \# Change default view
    usercategory normal
      * new-status
      * severity

    usercategory old-normal
      * status
      * severity
      * classification
</pre>
</dd>

<dt><code>help</code></dt>
<dd>
Requests that this help document be sent by email in plain ASCII.
</dd>

<dt><a name="stopprocessing"></a><code>quit</code></dt>
<dt><code>stop</code></dt>
<dt><code>thank</code></dt>
<dt><code>thanks</code></dt>
<dt><code>thankyou</code></dt>
<dt><code>thank you</code></dt>
<dt><code>--</code></dt>
<!-- #366093, I blame you! -->
<!-- <dt><code>kthxbye</code></dt> -->
<!-- See... I documented it! -->
<dd>
Stops processing at this point of the message.  After this you may
include any text you like, and it will be ignored.  You can use this
to include longer comments than are suitable for <code>#</code>, for
example for the benefit of human readers of your message (reading it
via the tracking system logs or due to a <code>CC</code> or
<code>BCC</code>).
</dd>

<dt><code>#</code>...</dt>
<dd>
One-line comment.  The <code>#</code> must be at the start of the
line.
</dd>

<dt><code>debug</code> <var>level</var></dt>
<dd>
Sets the debugging level to <var>level</var>, which should be a
nonnegative integer.  0 is no debugging; 1 is usually sufficient.  The
debugging output appears in the transcript.  It is not likely to be
useful to general users of the bug system.
</dd>

</dl>

<p>There is a <a href="server-refcard">reference card</a> for the
mailservers, available via the WWW, in
<code>bug-mailserver-refcard.txt</code> or by email using the
<code>refcard</code> command (see above).</p>

<p>If you wish to manipulate bug reports you should use the
<code>control@bugs.debian.org</code> address, which understands a
<a href="server-control">superset of the commands listed
above</a>.  This is described in another document, available on the
<a href="server-control">WWW</a>,
in the file <code>bug-maint-mailcontrol.txt</code>, or by
sending <code>help</code> to <code>control@bugs.debian.org</code>.</p>

<p>In case you are reading this as a plain text file or via email: an
HTML version is available via the bug system main contents page
<code>https://www.debian.org/Bugs/</code>.</p>

<hr />

#use "otherpages.inc"

#use "$(ENGLISHDIR)/Bugs/footer.inc"