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.  To change the originator of an open $gBug report,
  68   use the <code>submitter</code> command; note that this will inform the
  69   original submitter of the change.
  70
  71 <dt><code>submitter</code> <var>bugnumber</var>
  72 <var>originator-address</var> | <code>!</code>
  73
  74   <dd>Changes the originator of #<var>bugnumber</var> to
  75   <var>originator-address</var>.
  76
  77   <p>If you wish to become the new originator of the report you can use
  78   the <code>!</code> shorthand or specify your own email address.</p>
  79
  80   <p>While the <code>reopen</code> command changes the originator of other
  81   bugs merged with the one being reopened, <code>submitter</code> does not
  82   affect merged bugs.</p>
  83
  84 <dt><code>forwarded</code> <var>bugnumber</var> <var>address</var>
  85
  86   <dd>Notes that <var>bugnumber</var> has been forwarded to the upstream
  87   maintainer at <var>address</var>.  This does not actually forward the
  88   report.  This can be used to change an existing incorrect forwarded-to
  89   address, or to record a new one for a $gBug that wasn't previously noted
  90   as having been forwarded.
  91
  92 <dt><code>notforwarded</code> <var>bugnumber</var>
  93
  94   <dd>Forgets any idea that <var>bugnumber</var> has been forwarded to any
  95   upstream maintainer.  If the $gBug was not recorded as having been
  96   forwarded then this will do nothing.
  97
  98 <dt><code>retitle</code> <var>bugnumber</var> <var>new-title</var>
  99
 100   <dd>Changes the title of a $gBug report to that specified (the default is
 101   the <code>Subject</code> mail header from the original report).
 102
 103   <p>Unlike most of the other $gBug-manipulation commands when used on one of
 104   a set of merged reports this will change the title of only the
 105   individual $gBug requested, and not all those with which it is merged.
 106
 107 <dt><code>severity</code> <var>bugnumber</var> <var>severity</var>
 108
 109   <dd>Set the severity level for $gBug report #<var>bugnumber</var> to
 110   <var>severity</var>.  No notification is sent to the user who reported
 111   the $gBug.
 112
 113   <p>For <a href="Developer.html#severities">their meanings</a> please
 114   consult the general developers' documentation for the $gBug system.
 115
 116 <dt><code>clone</code> <var>bugnumber</var> [ <var>new IDs</var> ]
 117
 118   <dd>The clone control command allows you to duplicate a $gBug report. It is
 119   useful in the case where a single report actually indicates that multiple
 120   distinct $gBugs have occurred. "<var>New IDs</var>" are negative numbers,
 121   separated by spaces, which may be used in subsequent control commands to
 122   refer to the newly duplicated $gBugs. A new report is generated for each
 123   new ID.
 124
 125   <p>Example usage:</p>
 126
 127   <pre>
 128         clone 12345 -1 -2
 129         reassign -1 foo
 130         retitle -1 foo: foo sucks
 131         reassign -2 bar
 132         retitle -2 bar: bar sucks when used with foo
 133         severity -2 wishlist
 134         clone 123456 -3
 135         reassign -3 foo
 136         retitle -3 foo: foo sucks
 137         merge -1 -3
 138   </pre>
 139
 140 <dt><code>merge</code> <var>bugnumber</var> <var>bugnumber</var> ...
 141
 142   <dd>Merges two or more $gBug reports.  When reports are merged opening,
 143   closing, marking or unmarking as forwarded and reassigning any of the
 144   $gBugs to a new package will have an identical effect on all of the
 145   merged reports.
 146
 147   <p>Before $gBugs can be merged they must be in exactly the same state:
 148   either all open or all closed, with the same forwarded-to upstream
 149   author address or all not marked as forwarded, all assigned to the
 150   same package or package(s) (an exact string comparison is done on the
 151   package to which the $gBug is assigned), and all of the same severity.
 152   If they don't start out in the same state you should use
 153   <code>reassign</code>, <code>reopen</code> and so forth to make sure
 154   that they are before using <code>merge</code>. Titles are not required
 155   to match, and will not be affected by the merge.
 156
 157   <p>If any of the $gBugs listed in a <code>merge</code> command is already
 158   merged with another $gBug then all the reports merged with any of the
 159   ones listed will all be merged together.  Merger is like equality: it
 160   is reflexive, transitive and symmetric.
 161
 162   <p>Merging reports causes a note to appear on each report's logs; on the
 163   WWW pages this includes links to the other $gBugs.
 164
 165   <p>Merged reports are all expired simultaneously, and only when all of
 166   the reports each separately meet the criteria for expiry.
 167
 168 <dt><code>unmerge</code> <var>bugnumber</var>
 169
 170   <dd>Disconnects a $gBug report from any other reports with which it may have
 171   been merged.  If the report listed is merged with several others then
 172   they are all left merged with each other; only their associations with
 173   the $gBug explicitly named are removed.
 174
 175   <p>If many $gBug reports are merged and you wish to split them into two
 176   separate groups of merged reports you must unmerge each report in one
 177   of the new groups separately and then merge them into the required new
 178   group.
 179
 180   <p>You can only unmerge one report with each <code>unmerge</code>
 181   command; if you want to disconnect more than one $gBug simply include
 182   several <code>unmerge</code> commands in your message.
 183
 184 <dt><code>tags</code> <var>bugnumber</var> [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var>
 185
 186   <dd>Sets a particular tag for the $gBug report #<var>bugnumber</var> to
 187   <var>tag</var>. No notification is sent to the user who reported the $gBug.
 188   <code>+</code> means adding, <code>-</code> means subtracting, and
 189   <code>=</code> means ignoring the current tags and setting them afresh.
 190   The default action is adding.
 191
 192   <p>Available tags currently include <code>patch</code>, <code>wontfix</code>,
 193   <code>moreinfo</code>, <code>unreproducible</code>, <code>help</code>,
 194   <code>pending</code>, <code>fixed</code>, <code>security</code>,
 195   <code>upstream</code>, <code>potato</code>, <code>woody</code>,
 196   <code>sarge</code>,
 197   <code>sid</code> and <code>experimental</code>.
 198
 199   <p>For <a href="Developer.html#tags">their meanings</a> please consult the
 200   general developers' documentation for the $gBug system.
 201
 202 <dt><code>close</code> <var>bugnumber</var> (deprecated)
 203
 204   <dd>Close $gBug report #<var>bugnumber</var>.
 205
 206   <p>A notification is sent to the user who reported the $gBug, but (in
 207   contrast to mailing <var>bugnumber</var><code>-done@$gEmailDomain</code>) the
 208   text of the mail which caused the $gBug to be closed is <strong>not</strong>
 209   included in that notification.  The maintainer who closes a report
 210   should ensure, probably by sending a separate message, that the user
 211   who reported the $gBug knows why it is being closed.
 212   The use of this command is therefore deprecated.
 213
 214 <dt><code>package</code> [ <var>packagename</var> ... ]
 215
 216   <dd>Limits the following commands so that they will only apply to bugs
 217   filed against the listed packages. You can list one or more packages. If
 218   you don't list any packages, the following commands will apply to all
 219   bugs. You're encouraged to use this as a safety feature in case you
 220   accidentally use the wrong bug numbers.
 221
 222   <p>Example usage:</p>
 223
 224   <pre>
 225         package foo
 226         reassign 123456 bar
 227
 228         package bar
 229         retitle 123456 bar: bar sucks
 230         severity 123456 normal
 231
 232         package
 233         severity 234567 wishlist
 234   </pre>
 235
 236 <dt><code>owner</code> <var>bugnumber</var> <var>address</var> | <code>!</code>
 237
 238   <dd>Sets <var>address</var> to be the "owner" of #<var>bugnumber</var>.
 239   The owner of a $gBug claims responsibility for fixing it and will receive
 240   all mail regarding it.  This is useful to share out work in cases where a
 241   package has a team of maintainers.
 242
 243   <p>If you wish to become the owner of the $gBug yourself, you can use the
 244   <code>!</code> shorthand or specify your own email address.</p>
 245
 246 <dt><code>noowner</code> <var>bugnumber</var>
 247
 248   <dd>Forgets any idea that the $gBug has an owner other than the usual
 249   maintainer.  If the $gBug had no owner recorded then this will do nothing.
 250
 251 <dt><code>#</code>...
 252
 253   <dd>One-line comment. The <code>#</code> must be at the start of the line.
 254   The text of comments will be included in the acknowledgement sent to the
 255   sender and to affected maintainers, so you can use this to document the
 256   reasons for your commands.
 257
 258 <dt><code>quit</code>
 259 <dt><code>stop</code>
 260 <dt><code>thank</code>...
 261 <dt><code>--</code>...
 262
 263   <dd>Tells the control server to stop processing the message; the remainder
 264       of the message can include explanations, signatures or anything else,
 265       none of it will be detected by the control server.
 266
 267 </dl>
 268
 269 <hr>
 270
 271 <p>Other pages:
 272 <ul>
 273   <li><a href="./">$gBug tracking system main contents page.</a>
 274   <li><a href="Reporting.html">Instructions for reporting $gBugs.</a>
 275   <li><a href="Access.html">Accessing the $gBug tracking logs other than by WWW.</a>
 276   <li><a href="Developer.html">Developers' information regarding the $gBug processing system.</a>
 277   <li><a href="server-request.html">Fundamentals of the mailserver and commands for retrieving $gBugs.</a>
 278   <li><a href="server-refcard.html">Mailservers' reference card.</a>
 279   <li><a href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</a>
 280   <li><a href="db/ix/packages.html">Packages with $gBug reports.</a>
 281   <li><a href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</a>
 282 $gHTMLOtherPageList
 283 </ul>
 284
 285 $gHTMLTail
 286
 287 HTML_END