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