html/server-control.html.in

   1 $gControlHtml = <<HTML_END
   2 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
   3 <html>
   4 <head>
   5   <title>$gProject $gBug system - control mail server commands</title>
   6   <link rev="made" href="mailto:$gMaintainerEmail">
   7 </head>
   8 <body>
   9
  10 <h1>Introduction to the $gBug control and manipulation mailserver</h1>
  11
  12 <p>In addition to the mailserver on <code>request\@$gEmailDomain</code>
  13 which allows the retrieval of $gBug data and documentation by email,
  14 there is another server on <code>control\@$gEmailDomain</code> which
  15 also allows $gBug reports to be manipulated in various ways.</p>
  16
  17 <p>The control server works just like the request server, except that it
  18 has some additional commands; in fact, it's the same program.  The two
  19 addresses are only separated to avoid users making mistakes and
  20 causing problems while merely trying to request information.</p>
  21
  22 <p>Please see the
  23 <a href="server-request.html#introduction">introduction to the request
  24 server</a> available on the World Wide Web, in the file
  25 <code>bug-log-mailserver.txt</code>, or by sending
  26 <code>help</code> to either mailserver, for details of the basics of
  27 operating the mailservers and the common commands available when
  28 mailing either address.</p>
  29
  30 <p>The <a href="server-refcard.html">reference card</a> for the
  31 mailservers is available via the WWW, in
  32 <code>bug-mailserver-refcard.txt</code> or by email using the
  33 <code>refcard</code> command.</p>
  34
  35 <h1>Commands available at the control mailserver</h1>
  36
  37 <dl>
  38
  39 <dt><code>reassign</code> <var>bugnumber</var> <var>package</var>
  40
  41   <dd>Records that $gBug #<var>${gBug}number</var> is a $gBug in <var>package</var>.
  42   This can be used to set the package if the user forgot the
  43   pseudo-header, or to change an earlier assignment.  No notifications
  44   are sent to anyone (other than the usual information in the processing
  45   transcript).
  46
  47 <dt><code>reopen</code> <var>bugnumber</var>
  48  [ <var>originator-address</var> | <code>=</code> | <code>!</code> ]
  49
  50   <dd>Reopens #<var>bugnumber</var> if it is closed.
  51
  52   <p>By default, or if you specify <code>=</code>, the original submitter is
  53   still as the originator of the report, so that they will get the ack
  54   when it is closed again.
  55
  56   <p>If you supply an <var>originator-address</var> the originator will be
  57   set to the address you supply.  If you wish to become the new
  58   originator of the reopened report you can use the <code>!</code>
  59   shorthand or specify your own email address.
  60
  61   <p>It is usually a good idea to tell the person who is about to be
  62   recorded as the originator that you're reopening the report, so that
  63   they will know to expect the ack which they'll get when it is closed
  64   again.
  65
  66   <p>If the $gBug is not closed then reopen won't do anything, not even
  67   change the originator.  There is no way to change the originator of an
  68   open $gBug report (this is deliberate, so that you can't have a $gBug be
  69   closed and then deleted $gRemoveAge days later without someone being told about
  70   it).
  71
  72 <dt><code>forwarded</code> <var>bugnumber</var> <var>address</var>
  73
  74   <dd>Notes that <var>bugnumber</var> has been forwarded to the upstream
  75   maintainer at <var>address</var>.  This does not actually forward the
  76   report.  This can be used to change an existing incorrect forwarded-to
  77   address, or to record a new one for a $gBug that wasn't previously noted
  78   as having been forwarded.
  79
  80 <dt><code>notforwarded</code> <var>bugnumber</var>
  81
  82   <dd>Forgets any idea that <var>bugnumber</var> has been forwarded to any
  83   upstream maintainer.  If the $gBug was not recorded as having been
  84   forwarded then this will do nothing.
  85
  86 <dt><code>retitle</code> <var>bugnumber</var> <var>new-title</var>
  87
  88   <dd>Changes the title of a $gBug report to that specified (the default is
  89   the <code>Subject</code> mail header from the original report).
  90
  91   <p>Unlike most of the other $gBug-manipulation commands when used on one of
  92   a set of merged reports this will change the title of only the
  93   individual $gBug requested, and not all those with which it is merged.
  94
  95 <dt><code>severity</code> <var>bugnumber</var> <var>severity</var>
  96
  97   <dd>Set the severity level for $gBug report #<var>bugnumber</var> to
  98   <var>severity</var>.  No notification is sent to the user who reported
  99   the $gBug.
 100
 101   <p>For <a href="Developer.html#severities">their meanings</a> please
 102   consult the general developers' documentation for the $gBug system.
 103
 104 <dt><code>clone</code> <var>bugnumber</var> [ <var>new IDs</var> ]
 105
 106   <dd>The clone control command allows you to duplicate a $gBug report. It is
 107   useful in the case where a single report actually indicates that multiple
 108   distinct $gBugs have occurred. "<var>New IDs</var>" are negative numbers,
 109   separated by spaces, which may be used in subsequent control commands to
 110   refer to the newly duplicated $gBugs. A new report is generated for each
 111   new ID.
 112
 113   <p>Example usage:</p>
 114
 115   <pre>
 116         clone 12345 -1 -2
 117         reassign -1 foo
 118         retitle -1 foo: foo sucks
 119         reassign -2 bar
 120         retitle -2 bar: bar sucks when used with foo
 121         severity -2 wishlist
 122         clone 123456 -2
 123         reassign -2 foo
 124         retitle -2 foo: foo sucks
 125         merge -1 -2
 126   </pre>
 127
 128 <dt><code>merge</code> <var>bugnumber</var> <var>bugnumber</var> ...
 129
 130   <dd>Merges two or more $gBug reports.  When reports are merged opening,
 131   closing, marking or unmarking as forwarded and reassigning any of the
 132   $gBugs to a new package will have an identical effect on all of the
 133   merged reports.
 134
 135   <p>Before $gBugs can be merged they must be in exactly the same state:
 136   either all open or all closed, with the same forwarded-to upstream
 137   author address or all not marked as forwarded, all assigned to the
 138   same package or package(s) (an exact string comparison is done on the
 139   package to which the $gBug is assigned), and all of the same severity.
 140   If they don't start out in the same state you should use
 141   <code>reassign</code>, <code>reopen</code> and so forth to make sure
 142   that they are before using <code>merge</code>.
 143
 144   <p>If any of the $gBugs listed in a <code>merge</code> command is already
 145   merged with another $gBug then all the reports merged with any of the
 146   ones listed will all be merged together.  Merger is like equality: it
 147   is reflexive, transitive and symmetric.
 148
 149   <p>Merging reports causes a note to appear on each report's logs; on the
 150   WWW pages this includes links to the other $gBugs.
 151
 152   <p>Merged reports are all expired simultaneously, and only when all of
 153   the reports each separately meet the criteria for expiry.
 154
 155 <dt><code>unmerge</code> <var>bugnumber</var>
 156
 157   <dd>Disconnects a $gBug report from any other reports with which it may have
 158   been merged.  If the report listed is merged with several others then
 159   they are all left merged with each other; only their associations with
 160   the $gBug explicitly named are removed.
 161
 162   <p>If many $gBug reports are merged and you wish to split them into two
 163   separate groups of merged reports you must unmerge each report in one
 164   of the new groups separately and then merge them into the required new
 165   group.
 166
 167   <p>You can only unmerge one report with each <code>unmerge</code>
 168   command; if you want to disconnect more than one $gBug simply include
 169   several <code>unmerge</code> commands in your message.
 170
 171 <dt><code>tags</code> <var>bugnumber</var> [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var>
 172
 173   <dd>Sets a particular tag for the $gBug report #<var>bugnumber</var> to
 174   <var>tag</var>. No notification is sent to the user who reported the $gBug.
 175   <code>+</code> means adding, <code>-</code> means subtracting, and
 176   <code>=</code> means ignoring the current tags and setting them afresh.
 177   The default action is adding.
 178
 179   <p>Available tags currently include <code>patch</code>, <code>wontfix</code>,
 180   <code>moreinfo</code>, <code>unreproducible</code>, <code>help</code>,
 181   <code>pending</code>, <code>fixed</code>, <code>security</code>,
 182   <code>upstream</code>, <code>potato</code>, <code>woody</code>,
 183   <code>sarge</code>,
 184   <code>sid</code> and <code>experimental</code>.
 185
 186   <p>For <a href="Developer.html#tags">their meanings</a> please consult the
 187   general developers' documentation for the $gBug system.
 188
 189 <dt><code>close</code> <var>bugnumber</var>
 190
 191   <dd>Close $gBug report #<var>bugnumber</var>.
 192
 193   <p>A notification is sent to the user who reported the $gBug, but (in
 194   contrast to mailing <var>bugnumber</var><code>-done@$gEmailDomain</code>) the
 195   text of the mail which caused the $gBug to be closed is <strong>not</strong>
 196   included in that notification.  The maintainer who closes a report
 197   should ensure, probably by sending a separate message, that the user
 198   who reported the $gBug knows why it is being closed.
 199   The use of this command is therefore deprecated.
 200
 201 <dt><code>quit</code>
 202 <dt><code>stop</code>
 203 <dt><code>thank</code>...
 204 <dt><code>--</code>...
 205
 206   <dd>Tells the control server to stop processing the message; the remainder
 207       of the message can include explanations, signatures or anything else,
 208       none of it will be detected by the control server.
 209
 210 <dt><code>#</code>...
 211
 212   <dd>One-line comment. The <code>#</code> must be at the start of the line.
 213
 214 </dl>
 215
 216 <hr>
 217
 218 <p>Other pages:
 219 <ul>
 220   <li><a href="./">$gBug tracking system main contents page.</a>
 221   <li><a href="Reporting.html">Instructions for reporting $gBugs.</a>
 222   <li><a href="Access.html">Accessing the $gBug tracking logs other than by WWW.</a>
 223   <li><a href="Developer.html">Developers' information regarding the $gBug processing system.</a>
 224   <li><a href="server-request.html">Fundamentals of the mailserver and commands for retrieving $gBugs.</a>
 225   <li><a href="server-refcard.html">Mailservers' reference card.</a>
 226   <li><a href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</a>
 227   <li><a href="db/ix/packages.html">Packages with $gBug reports.</a>
 228   <li><a href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</a>
 229 $gHTMLOtherPageList
 230 </ul>
 231
 232 $gHTMLTail
 233
 234 HTML_END