$gControlHtml = < $gProject $gBug system - control mail server commands

Introduction to the $gBug control and manipulation mailserver

In addition to the mailserver on request\@$gEmailDomain which allows the retrieval of $gBug data and documentation by email, there is another server on control\@$gEmailDomain which also allows $gBug reports to be manipulated in various ways.

The control server works just like the request server, except that it has some additional commands; in fact, it's the same program. The two addresses are only separated to avoid users making mistakes and causing problems while merely trying to request information.

Please see the introduction to the request server available on the World Wide Web, in the file bug-log-mailserver.txt, or by sending help to either mailserver, for details of the basics of operating the mailservers and the common commands available when mailing either address.

The reference card for the mailservers is available via the WWW, in bug-mailserver-refcard.txt or by email using the refcard command.

Commands available at the control mailserver

reassign bugnumber package [ version ]
Records that $gBug #${gBug}number is a $gBug in package. This can be used to set the package if the user forgot the pseudo-header, or to change an earlier assignment. No notifications are sent to anyone (other than the usual information in the processing transcript).

If you supply a version, the $gBug tracking system will note that the $gBug affects that version of the newly-assigned package.

reopen bugnumber [ originator-address | = | ! ]
Reopens #bugnumber if it is closed.

By default, or if you specify =, the original submitter is still as the originator of the report, so that they will get the ack when it is closed again.

If you supply an originator-address the originator will be set to the address you supply. If you wish to become the new originator of the reopened report you can use the ! shorthand or specify your own email address.

It is usually a good idea to tell the person who is about to be recorded as the originator that you're reopening the report, so that they will know to expect the ack which they'll get when it is closed again.

If the $gBug is not closed then reopen won't do anything, not even change the originator. To change the originator of an open $gBug report, use the submitter command; note that this will inform the original submitter of the change.

If the $gBug was recorded as being closed in a particular version of a package but recurred in a later version, it is better to use the found command instead.

found bugnumber [ version ]
Record that #bugnumber has been encountered in the given version of the package to which it is assigned.

The $gBug tracking system uses this information, in conjunction with fixed versions recorded when closing $gBugs, to display lists of $gBugs open in various versions of each package. It considers a $gBug to be open when it has no fixed version, or when it has been found more recently than it has been fixed.

If no version is given, then the list of fixed versions for the $gBug is cleared. This is identical to the behaviour of reopen.

This command will only cause a bug to be marked as not done if no version is specified, or if the version being marked found is equal to the version which was last marked fixed. (If you are certain that you want the bug marked as not done, use reopen in conjunction with found.

This command was introduced in preference to reopen because it was difficult to add a version to that command's syntax without suffering ambiguity.

notfound bugnumber version
Remove the record that #bugnumber was encountered in the given version of the package to which it is assigned.

This differs from closing the $gBug at that version in that the $gBug is not listed as fixed in that version either; no information about that version will be known. It is intended for fixing mistakes in the record of when a $gBug was found.

submitter bugnumber originator-address | !
Changes the originator of #bugnumber to originator-address.

If you wish to become the new originator of the report you can use the ! shorthand or specify your own email address.

While the reopen command changes the originator of other bugs merged with the one being reopened, submitter does not affect merged bugs.

forwarded bugnumber address
Notes that bugnumber has been forwarded to the upstream maintainer at address. This does not actually forward the report. This can be used to change an existing incorrect forwarded-to address, or to record a new one for a $gBug that wasn't previously noted as having been forwarded.
notforwarded bugnumber
Forgets any idea that bugnumber has been forwarded to any upstream maintainer. If the $gBug was not recorded as having been forwarded then this will do nothing.
retitle bugnumber new-title
Changes the title of a $gBug report to that specified (the default is the Subject mail header from the original report).

Unlike most of the other $gBug-manipulation commands when used on one of a set of merged reports this will change the title of only the individual $gBug requested, and not all those with which it is merged.

severity bugnumber severity
Set the severity level for $gBug report #bugnumber to severity. No notification is sent to the user who reported the $gBug.

For their meanings please consult the general developers' documentation for the $gBug system.

clone bugnumber NewID [ new IDs ... ]
The clone control command allows you to duplicate a $gBug report. It is useful in the case where a single report actually indicates that multiple distinct $gBugs have occurred. "New IDs" are negative numbers, separated by spaces, which may be used in subsequent control commands to refer to the newly duplicated $gBugs. A new report is generated for each new ID.

Example usage:

        clone 12345 -1 -2
        reassign -1 foo
        retitle -1 foo: foo sucks
        reassign -2 bar
        retitle -2 bar: bar sucks when used with foo
        severity -2 wishlist
        clone 123456 -3
        reassign -3 foo
        retitle -3 foo: foo sucks
        merge -1 -3
  
merge bugnumber bugnumber ...
Merges two or more $gBug reports. When reports are merged opening, closing, marking or unmarking as forwarded and reassigning any of the $gBugs to a new package will have an identical effect on all of the merged reports.

Before $gBugs can be merged they must be in exactly the same state: either all open or all closed, with the same forwarded-to upstream author address or all not marked as forwarded, all assigned to the same package or package(s) (an exact string comparison is done on the package to which the $gBug is assigned), and all of the same severity. If they don't start out in the same state you should use reassign, reopen and so forth to make sure that they are before using merge. Titles are not required to match, and will not be affected by the merge.

If any of the $gBugs listed in a merge command is already merged with another $gBug then all the reports merged with any of the ones listed will all be merged together. Merger is like equality: it is reflexive, transitive and symmetric.

Merging reports causes a note to appear on each report's logs; on the WWW pages this includes links to the other $gBugs.

Merged reports are all expired simultaneously, and only when all of the reports each separately meet the criteria for expiry.

forcemerge bugnumber bugnumber ...
Forcibly merges two or more $gBug reports. The first bug is chosen as the master bug, and its seetings are assigned to the bugs listed next in the command. See the text above for a description of what merging means.
unmerge bugnumber
Disconnects a $gBug report from any other reports with which it may have been merged. If the report listed is merged with several others then they are all left merged with each other; only their associations with the $gBug explicitly named are removed.

If many $gBug reports are merged and you wish to split them into two separate groups of merged reports you must unmerge each report in one of the new groups separately and then merge them into the required new group.

You can only unmerge one report with each unmerge command; if you want to disconnect more than one $gBug simply include several unmerge commands in your message.

tags bugnumber [ + | - | = ] tag [ tag ... ]
Sets tags for the $gBug report #bugnumber. No notification is sent to the user who reported the $gBug. Setting the action to + means to add each given tag, - means to remove each given tag, and = means to ignore the current tags and set them afresh to the list provided. The default action is adding.

Example usage:

        # same as 'tags 123456 + patch'
        tags 123456 patch

        # same as 'tags 123456 + help security'
        tags 123456 help security

        # add 'fixed' and 'pending' tags
        tags 123456 + fixed pending

        # remove 'unreproducible' tag
        tags 123456 - unreproducible

        # set tags to exactly 'moreinfo' and 'unreproducible'
        tags 123456 = moreinfo unreproducible
  

Available tags currently include patch, wontfix, moreinfo, unreproducible, help, pending, fixed, security, upstream, potato, woody, sarge, sid and experimental.

For their meanings please consult the general developers' documentation for the $gBug system.

block|unblock bugnumber by|with bug [ bug ... ]
Use to note that one bug blocks another bug from being fixed. The first listed bug is the one being blocked, and it is followed by the bug or bugs that are blocking it. Use unblock to unblock a bug.

Example usage:

        # indicates that 7890 cannot be fixed until 123456 is fixed
        block 7890 by 123456
        # indicates that 7890 can be fixed before 123456 after all
        unblock 7890 by 123456
  
close bugnumber [ fixed-version ] (deprecated)
Close $gBug report #bugnumber.

A notification is sent to the user who reported the $gBug, but (in contrast to mailing bugnumber-done@$gEmailDomain) the text of the mail which caused the $gBug to be closed is not included in that notification. The maintainer who closes a report should ensure, probably by sending a separate message, that the user who reported the $gBug knows why it is being closed. The use of this command is therefore deprecated.

If you supply a fixed-version, the $gBug tracking system will note that the $gBug was fixed in that version of the package.

package [ packagename ... ]
Limits the following commands so that they will only apply to bugs filed against the listed packages. You can list one or more packages. If you don't list any packages, the following commands will apply to all bugs. You're encouraged to use this as a safety feature in case you accidentally use the wrong bug numbers.

Example usage:

        package foo
        reassign 123456 bar 1.0-1

        package bar
        retitle 123456 bar: bar sucks
        severity 123456 normal

        package
        severity 234567 wishlist
  
owner bugnumber address | !
Sets address to be the "owner" of #bugnumber. The owner of a $gBug claims responsibility for fixing it. This is useful to share out work in cases where a package has a team of maintainers.

If you wish to become the owner of the $gBug yourself, you can use the ! shorthand or specify your own email address.

noowner bugnumber
Forgets any idea that the $gBug has an owner other than the usual maintainer. If the $gBug had no owner recorded then this will do nothing.
archive bugnumber
Archives a $gBug that was previously archived if the $gBug fulfills the requirements for archival, ignoring time.
unarchive bugnumber
Unarchives a $gBug that was previously archived. Unarchival should generally be coupled with reopen and found/fixed as approprite. Bugs that have been unarchived can be archived using archive assuming the non-time based archival requirements are met.
#...
One-line comment. The # must be at the start of the line. The text of comments will be included in the acknowledgement sent to the sender and to affected maintainers, so you can use this to document the reasons for your commands.
quit
stop
thank
thanks
thankyou
thank you
--
On a line by itself, in any case, possibly followed by whitespace, tells the control server to stop processing the message; the remainder of the message can include explanations, signatures or anything else, none of it will be detected by the control server.

Other pages:

$gHTMLTail HTML_END