1 $gControlHtml = <<HTML_END
2 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
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">
11 <h1>Introduction to the $gBug control and manipulation mailserver</h1>
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>
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>
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>
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>
36 <h1>Commands available at the control mailserver</h1>
40 <dt><code>reassign</code> <var>bugnumber</var> <var>package</var>
41 [ <var>version</var> ]
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
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.
52 <dt><code>reopen</code> <var>bugnumber</var>
53 [ <var>originator-address</var> | <code>=</code> | <code>!</code> ]
55 <dd>Reopens #<var>bugnumber</var> if it is closed.
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.
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.
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
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.
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.
80 <dt><code>found</code> <var>bugnumber</var> [ <var>version</var> ]
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.
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
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
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>
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.
105 <dt><code>notfound</code> <var>bugnumber</var> <var>version</var>
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.
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.
115 <dt><code>submitter</code> <var>bugnumber</var>
116 <var>originator-address</var> | <code>!</code>
118 <dd>Changes the originator of #<var>bugnumber</var> to
119 <var>originator-address</var>.
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>
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>
128 <dt><code>forwarded</code> <var>bugnumber</var> <var>address</var>
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.
136 <dt><code>notforwarded</code> <var>bugnumber</var>
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.
142 <dt><code>retitle</code> <var>bugnumber</var> <var>new-title</var>
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).
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.
151 <dt><code>severity</code> <var>bugnumber</var> <var>severity</var>
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
157 <p>For <a href="Developer.html#severities">their meanings</a> please
158 consult the general developers' documentation for the $gBug system.
160 <dt><code>clone</code> <var>bugnumber</var> <var>NewID</var> [ <var>new IDs</var> ... ]
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
169 <p>Example usage:</p>
174 retitle -1 foo: foo sucks
176 retitle -2 bar: bar sucks when used with foo
180 retitle -3 foo: foo sucks
184 <dt><code>merge</code> <var>bugnumber</var> <var>bugnumber</var> ...
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
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.
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.
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.
209 <p>Merged reports are all expired simultaneously, and only when all of
210 the reports each separately meet the criteria for expiry.
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
218 <dt><code>unmerge</code> <var>bugnumber</var>
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.
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
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.
234 <dt><code>tags</code> <var>bugnumber</var> [ <code>+</code> | <code>-</code> | <code>=</code> ] <var>tag</var> [ <var>tag</var> ... ]
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.
243 <p>Example usage:</p>
246 # same as 'tags 123456 + patch'
249 # same as 'tags 123456 + help security'
250 tags 123456 help security
252 # add 'fixed' and 'pending' tags
253 tags 123456 + fixed pending
255 # remove 'unreproducible' tag
256 tags 123456 - unreproducible
258 # set tags to exactly 'moreinfo' and 'unreproducible'
259 tags 123456 = moreinfo unreproducible
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>,
267 <code>sid</code> and <code>experimental</code>.
269 <p>For <a href="Developer.html#tags">their meanings</a> please consult the
270 general developers' documentation for the $gBug system.
272 <dt><code>block</code>|<code>unblock</code> <var>bugnumber</var> <code>by</code>|<code>with</code> <var>bug</var> [ <var>bug</var> ... ]
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>
279 <p>Example usage:</p>
282 # indicates that 7890 cannot be fixed until 123456 is fixed
284 # indicates that 7890 can be fixed before 123456 after all
285 unblock 7890 by 123456
288 <dt><code>close</code> <var>bugnumber</var> [ <var>fixed-version</var> ]
291 <dd>Close $gBug report #<var>bugnumber</var>.
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.
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.
304 <dt><code>package</code> [ <var>packagename</var> ... ]
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.
312 <p>Example usage:</p>
316 reassign 123456 bar 1.0-1
319 retitle 123456 bar: bar sucks
320 severity 123456 normal
323 severity 234567 wishlist
326 <dt><code>owner</code> <var>bugnumber</var> <var>address</var> | <code>!</code>
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.
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>
336 <dt><code>noowner</code> <var>bugnumber</var>
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.
341 <dt><code>archive</code> <var>bugnumber</var>
343 <dd>Archives a $gBug that was previously archived if the $gBug
344 fulfills the requirements for archival, ignoring time.
346 <dt><code>unarchive</code> <var>bugnumber</var>
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.
353 <dt><code>#</code>...
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.
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>
367 <!-- #366093, I blame you! -->
368 <!-- <dt><code>kthxbye</code> -->
369 <!-- See... I documented it! -->
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
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>