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   <link rel="stylesheet" href="$gWebHostBugDir/css/bugs.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <h1>Introduction to the $gBug control and manipulation mailserver</h1>
  12
  13 <p>In addition to the mailserver on <code>request\@$gEmailDomain</code>
  14 which allows the retrieval of $gBug data and documentation by email,
  15 there is another server on <code>control\@$gEmailDomain</code> which
  16 also allows $gBug reports to be manipulated in various ways.</p>
  17
  18 <p>The control server works just like the request server, except that it
  19 has some additional commands; in fact, it's the same program.  The two
  20 addresses are only separated to avoid users making mistakes and
  21 causing problems while merely trying to request information.</p>
  22
  23 <p>Please see the
  24 <a href="server-request.html#introduction">introduction to the request
  25 server</a> available on the World Wide Web, in the file
  26 <code>bug-log-mailserver.txt</code>, or by sending
  27 <code>help</code> to either mailserver, for details of the basics of
  28 operating the mailservers and the common commands available when
  29 mailing either address.</p>
  30
  31 <p>The <a href="server-refcard.html">reference card</a> for the
  32 mailservers is available via the WWW, in
  33 <code>bug-mailserver-refcard.txt</code> or by email using the
  34 <code>refcard</code> command.</p>
  35
  36 <h1>Commands available at the control mailserver</h1>
  37
  38 <dl>
  39
  40 <dt><code>reassign</code> <var>bugnumber</var> <var>package</var>
  41  [ <var>version</var> ]
  42
  43   <dd>Records that $gBug #<var>${gBug}number</var> is a $gBug in <var>package</var>.
  44   This can be used to set the package if the user forgot the
  45   pseudo-header, or to change an earlier assignment.  No notifications
  46   are sent to anyone (other than the usual information in the processing
  47   transcript).
  48
  49   <p>If you supply a <var>version</var>, the $gBug tracking system will note
  50   that the $gBug affects that version of the newly-assigned package.
  51
  52 <dt><code>reopen</code> <var>bugnumber</var>
  53  [ <var>originator-address</var> | <code>=</code> | <code>!</code> ]
  54
  55   <dd>Reopens #<var>bugnumber</var> if it is closed.
  56
  57   <p>By default, or if you specify <code>=</code>, the original submitter is
  58   still as the originator of the report, so that they will get the ack
  59   when it is closed again.
  60
  61   <p>If you supply an <var>originator-address</var> the originator will be
  62   set to the address you supply.  If you wish to become the new
  63   originator of the reopened report you can use the <code>!</code>
  64   shorthand or specify your own email address.
  65
  66   <p>It is usually a good idea to tell the person who is about to be
  67   recorded as the originator that you're reopening the report, so that
  68   they will know to expect the ack which they'll get when it is closed
  69   again.
  70
  71   <p>If the $gBug is not closed then reopen won't do anything, not even
  72   change the originator.  To change the originator of an open $gBug report,
  73   use the <code>submitter</code> command; note that this will inform the
  74   original submitter of the change.
  75
  76   <p>If the $gBug was recorded as being closed in a particular version of a
  77   package but recurred in a later version, it is better to use the
  78   <code>found</code> command instead.
  79
  80 <dt><code>found</code> <var>bugnumber</var> [ <var>version</var> ]
  81
  82   <dd>Record that #<var>bugnumber</var> has been encountered in the given
  83   <var>version</var> of the package to which it is assigned.
  84
  85   <p>The $gBug tracking system uses this information, in conjunction with
  86   fixed versions recorded when closing $gBugs, to display lists of $gBugs
  87   open in various versions of each package. It considers a $gBug to be open
  88   when it has no fixed version, or when it has been found more recently than
  89   it has been fixed.
  90
  91   <p>If no <var>version</var> is given, then the list of fixed versions for
  92   the $gBug is cleared. This is identical to the behaviour of
  93   <code>reopen</code>.
  94
  95   <p>This command will only cause a bug to be marked as not done if no
  96     version is specified, or if the <var>version</var> being marked found
  97     is equal to the <var>version</var> which was last marked fixed. (If
  98     you are certain that you want the bug marked as not done,
  99     use <code>reopen</code> in conjunction with <code>found</code>.</p>
 100
 101   <p>This command was introduced in preference to <code>reopen</code>
 102   because it was difficult to add a <var>version</var> to that command's
 103   syntax without suffering ambiguity.
 104
 105 <dt><code>notfound</code> <var>bugnumber</var> <var>version</var>
 106
 107   <dd>Remove the record that #<var>bugnumber</var> was encountered in the
 108   given <var>version</var> of the package to which it is assigned.
 109
 110   <p>This differs from closing the $gBug at that version in that the $gBug
 111   is not listed as fixed in that version either; no information about that
 112   version will be known. It is intended for fixing mistakes in the record of
 113   when a $gBug was found.
 114
 115 <dt><code>submitter</code> <var>bugnumber</var>
 116 <var>originator-address</var> | <code>!</code>
 117
 118   <dd>Changes the originator of #<var>bugnumber</var> to
 119   <var>originator-address</var>.
 120
 121   <p>If you wish to become the new originator of the report you can use
 122   the <code>!</code> shorthand or specify your own email address.</p>
 123
 124   <p>While the <code>reopen</code> command changes the originator of other
 125   bugs merged with the one being reopened, <code>submitter</code> does not
 126   affect merged bugs.</p>
 127
 128 <dt><code>forwarded</code> <var>bugnumber</var> <var>address</var>
 129
 130   <dd>Notes that <var>bugnumber</var> has been forwarded to the upstream
 131   maintainer at <var>address</var>.  This does not actually forward the
 132   report.  This can be used to change an existing incorrect forwarded-to
 133   address, or to record a new one for a $gBug that wasn't previously noted
 134   as having been forwarded.
 135
 136 <dt><code>notforwarded</code> <var>bugnumber</var>
 137
 138   <dd>Forgets any idea that <var>bugnumber</var> has been forwarded to any
 139   upstream maintainer.  If the $gBug was not recorded as having been
 140   forwarded then this will do nothing.
 141
 142 <dt><code>retitle</code> <var>bugnumber</var> <var>new-title</var>
 143
 144   <dd>Changes the title of a $gBug report to that specified (the default is
 145   the <code>Subject</code> mail header from the original report).
 146
 147   <p>Unlike most of the other $gBug-manipulation commands when used on one of
 148   a set of merged reports this will change the title of only the
 149   individual $gBug requested, and not all those with which it is merged.
 150
 151 <dt><code>severity</code> <var>bugnumber</var> <var>severity</var>
 152
 153   <dd>Set the severity level for $gBug report #<var>bugnumber</var> to
 154   <var>severity</var>.  No notification is sent to the user who reported
 155   the $gBug.
 156
 157   <p>For <a href="Developer.html#severities">their meanings</a> please
 158   consult the general developers' documentation for the $gBug system.
 159
 160 <dt><code>clone</code> <var>bugnumber</var> <var>NewID</var> [ <var>new IDs</var> ... ]
 161
 162   <dd>The clone control command allows you to duplicate a $gBug report. It is
 163   useful in the case where a single report actually indicates that multiple
 164   distinct $gBugs have occurred. "<var>New IDs</var>" are negative numbers,
 165   separated by spaces, which may be used in subsequent control commands to
 166   refer to the newly duplicated $gBugs. A new report is generated for each
 167   new ID.
 168
 169   <p>Example usage:</p>
 170
 171   <pre>
 172         clone 12345 -1 -2
 173         reassign -1 foo
 174         retitle -1 foo: foo sucks
 175         reassign -2 bar
 176         retitle -2 bar: bar sucks when used with foo
 177         severity -2 wishlist
 178         clone 123456 -3
 179         reassign -3 foo
 180         retitle -3 foo: foo sucks
 181         merge -1 -3
 182   </pre>
 183
 184 <dt><code>merge</code> <var>bugnumber</var> <var>bugnumber</var> ...
 185
 186   <dd>Merges two or more $gBug reports.  When reports are merged opening,
 187   closing, marking or unmarking as forwarded and reassigning any of the
 188   $gBugs to a new package will have an identical effect on all of the
 189   merged reports.
 190
 191   <p>Before $gBugs can be merged they must be in exactly the same state:
 192   either all open or all closed, with the same forwarded-to upstream
 193   author address or all not marked as forwarded, all assigned to the
 194   same package or package(s) (an exact string comparison is done on the
 195   package to which the $gBug is assigned), and all of the same severity.
 196   If they don't start out in the same state you should use
 197   <code>reassign</code>, <code>reopen</code> and so forth to make sure
 198   that they are before using <code>merge</code>. Titles are not required
 199   to match, and will not be affected by the merge.
 200
 201   <p>If any of the $gBugs listed in a <code>merge</code> command is already
 202   merged with another $gBug then all the reports merged with any of the
 203   ones listed will all be merged together.  Merger is like equality: it
 204   is reflexive, transitive and symmetric.
 205
 206   <p>Merging reports causes a note to appear on each report's logs; on the
 207   WWW pages this includes links to the other $gBugs.
 208
 209   <p>Merged reports are all expired simultaneously, and only when all of
 210   the reports each separately meet the criteria for expiry.
 211
 212 <dt><code>forcemerge</code> <var>bugnumber</var> <var>bugnumber</var> ...
 213   <dd>Forcibly merges two or more $gBug reports. The first bug is
 214   chosen as the master bug, and its seetings are assigned to the bugs
 215   listed next in the command. See the text above for a description of
 216   what merging means.
 217
 218 <dt><code>unmerge</code> <var>bugnumber</var>
 219
 220   <dd>Disconnects a $gBug report from any other reports with which it may have
 221   been merged.  If the report listed is merged with several others then
 222   they are all left merged with each other; only their associations with
 223   the $gBug explicitly named are removed.
 224
 225   <p>If many $gBug reports are merged and you wish to split them into two
 226   separate groups of merged reports you must unmerge each report in one
 227   of the new groups separately and then merge them into the required new
 228   group.
 229
 230   <p>You can only unmerge one report with each <code>unmerge</code>
 231   command; if you want to disconnect more than one $gBug simply include
 232   several <code>unmerge</code> commands in your message.
 233
 234 <dt><code>tags</code> <var>bugnumber</var> [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var> [ <var>tag</var> ... ]
 235
 236   <dd>Sets tags for the $gBug report #<var>bugnumber</var>. No notification
 237   is sent to the user who reported the $gBug. Setting the action to
 238   <code>+</code> means to add each given <var>tag</var>, <code>-</code>
 239   means to remove each given <var>tag</var>, and <code>=</code> means to
 240   ignore the current tags and set them afresh to the list provided. The
 241   default action is adding.
 242
 243   <p>Example usage:</p>
 244
 245   <pre>
 246         # same as 'tags 123456 + patch'
 247         tags 123456 patch
 248
 249         # same as 'tags 123456 + help security'
 250         tags 123456 help security
 251
 252         # add 'fixed' and 'pending' tags
 253         tags 123456 + fixed pending
 254
 255         # remove 'unreproducible' tag
 256         tags 123456 - unreproducible
 257
 258         # set tags to exactly 'moreinfo' and 'unreproducible'
 259         tags 123456 = moreinfo unreproducible
 260   </pre>
 261
 262   <p>Available tags currently include <code>patch</code>, <code>wontfix</code>,
 263   <code>moreinfo</code>, <code>unreproducible</code>, <code>help</code>,
 264   <code>pending</code>, <code>fixed</code>, <code>security</code>,
 265   <code>upstream</code>, <code>potato</code>, <code>woody</code>,
 266   <code>sarge</code>,
 267   <code>sid</code> and <code>experimental</code>.
 268
 269   <p>For <a href="Developer.html#tags">their meanings</a> please consult the
 270   general developers' documentation for the $gBug system.
 271
 272 <dt><code>block</code>|<code>unblock</code> <var>bugnumber</var> <code>by</code>|<code>with</code> <var>bug</var> [ <var>bug</var> ... ]
 273
 274   <dd>Use to note that one bug blocks another bug from being fixed.
 275   The first listed bug is the one being blocked, and it is followed
 276   by the bug or bugs that are blocking it. Use <code>unblock</code>
 277   to unblock a bug.
 278
 279   <p>Example usage:</p>
 280
 281   <pre>
 282         # indicates that 7890 cannot be fixed until 123456 is fixed
 283         block 7890 by 123456
 284         # indicates that 7890 can be fixed before 123456 after all
 285         unblock 7890 by 123456
 286   </pre>
 287
 288 <dt><code>close</code> <var>bugnumber</var> [ <var>fixed-version</var> ]
 289  (deprecated)
 290
 291   <dd>Close $gBug report #<var>bugnumber</var>.
 292
 293   <p>A notification is sent to the user who reported the $gBug, but (in
 294   contrast to mailing <var>bugnumber</var><code>-done@$gEmailDomain</code>) the
 295   text of the mail which caused the $gBug to be closed is <strong>not</strong>
 296   included in that notification.  The maintainer who closes a report
 297   should ensure, probably by sending a separate message, that the user
 298   who reported the $gBug knows why it is being closed.
 299   The use of this command is therefore deprecated.
 300
 301   <p>If you supply a <var>fixed-version</var>, the $gBug tracking system
 302   will note that the $gBug was fixed in that version of the package.
 303
 304 <dt><code>package</code> [ <var>packagename</var> ... ]
 305
 306   <dd>Limits the following commands so that they will only apply to bugs
 307   filed against the listed packages. You can list one or more packages. If
 308   you don't list any packages, the following commands will apply to all
 309   bugs. You're encouraged to use this as a safety feature in case you
 310   accidentally use the wrong bug numbers.
 311
 312   <p>Example usage:</p>
 313
 314   <pre>
 315         package foo
 316         reassign 123456 bar 1.0-1
 317
 318         package bar
 319         retitle 123456 bar: bar sucks
 320         severity 123456 normal
 321
 322         package
 323         severity 234567 wishlist
 324   </pre>
 325
 326 <dt><code>owner</code> <var>bugnumber</var> <var>address</var> | <code>!</code>
 327
 328   <dd>Sets <var>address</var> to be the "owner" of #<var>bugnumber</var>.
 329   The owner of a $gBug claims responsibility for fixing it.
 330   This is useful to share out work in cases where a
 331   package has a team of maintainers.
 332
 333   <p>If you wish to become the owner of the $gBug yourself, you can use the
 334   <code>!</code> shorthand or specify your own email address.</p>
 335
 336 <dt><code>noowner</code> <var>bugnumber</var>
 337
 338   <dd>Forgets any idea that the $gBug has an owner other than the usual
 339   maintainer.  If the $gBug had no owner recorded then this will do nothing.
 340
 341 <dt><code>archive</code> <var>bugnumber</var>
 342
 343   <dd>Archives a $gBug that was previously archived if the $gBug
 344   fulfills the requirements for archival, ignoring time.
 345
 346 <dt><code>unarchive</code> <var>bugnumber</var>
 347
 348   <dd>Unarchives a $gBug that was previously archived. Unarchival
 349   should generally be coupled with reopen and found/fixed as
 350   approprite. Bugs that have been unarchived can be archived using
 351   archive assuming the non-time based archival requirements are met.
 352
 353 <dt><code>#</code>...
 354
 355   <dd>One-line comment. The <code>#</code> must be at the start of the line.
 356   The text of comments will be included in the acknowledgement sent to the
 357   sender and to affected maintainers, so you can use this to document the
 358   reasons for your commands.
 359
 360 <dt><code>quit</code>
 361 <dt><code>stop</code>
 362 <dt><code>thank</code>
 363 <dt><code>thanks</code>
 364 <dt><code>thankyou</code>
 365 <dt><code>thank you</code>
 366 <dt><code>--</code>
 367 <!-- #366093, I blame you! -->
 368 <!-- <dt><code>kthxbye</code> -->
 369 <!-- See... I documented it! -->
 370
 371   <dd>On a line by itself, in any case, possibly followed by
 372       whitespace, tells the control server to stop processing the
 373       message; the remainder of the message can include explanations,
 374       signatures or anything else, none of it will be detected by the
 375       control server.
 376
 377 </dl>
 378
 379 <hr>
 380
 381 <p>Other pages:
 382 <ul>
 383   <li><a href="./">$gBug tracking system main contents page.</a>
 384   <li><a href="Reporting.html">Instructions for reporting $gBugs.</a>
 385   <li><a href="Access.html">Accessing the $gBug tracking logs other than by WWW.</a>
 386   <li><a href="Developer.html">Developers' information regarding the $gBug processing system.</a>
 387   <li><a href="server-request.html">Fundamentals of the mailserver and commands for retrieving $gBugs.</a>
 388   <li><a href="server-refcard.html">Mailservers' reference card.</a>
 389   <li><a href="db/ix/full.html">Full list of outstanding and recent $gBug reports.</a>
 390   <li><a href="db/ix/packages.html">Packages with $gBug reports.</a>
 391   <li><a href="db/ix/maintainers.html">Maintainers of packages with $gBug reports.</a>
 392 $gHTMLOtherPageList
 393 </ul>
 394
 395 $gHTMLTail
 396
 397 HTML_END