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