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