Debbugs User Guide

Table of Contents

Next:   [Contents][Index]

Debbugs User Guide

Debbugs is a bugtracking system (BTS) that was initially written for the Debian project but currently used also by the GNU project. The main distinctive feature of Debbugs is that it’s mostly email-based. All actions on bug reports: opening, closing, changing the status, commenting, forwarding are performed via email by sending specially composed letters to the particular email addresses. However, searching the bug reports, querying bug report status and viewing comments have been web-based for a long time. To overcome this inconvenience the Debbugs/SOAP service was introduced.

Based on the Debbugs/SOAP service, frontends are written which offer handling of bugs inside Emacs. These frontends are restricted to the GNU Debbugs server. Bugs are presented either as tabulated list (debbugs-gnu) or as org-mode TODO list (debbugs-org, see (org)Org Mode). As backend they use the debbugs Emacs library (see (debbugs)Debbugs Programmer’s Manual).


Next: , Previous: , Up: Top   [Contents][Index]

1 Retrieving Bugs

Bugs are retrieved by the debbugs-gnu or debbugs-org commands. In their simple version, they retrieve just bugs for the "emacs" package on the GNU Debbugs server, filtered by bug severities. Further filtering is possible when the commands are called with a prefix.

When the bug numbers to be retrieved are known, the commands debbugs-gnu-bugs or debbugs-org-bugs are applicable.

The commands debbugs-gnu-patches / debbugs-org-patches, debbugs-gnu-tagged / debbugs-org-tagged and debbugs-gnu-emacs-release-blocking-reports / debbugs-org-emacs-release-blocking-reports retrieve bugs with a predefined filter.

Command: debbugs-gnu severities &optional packages archivedp suppress tags
Command: debbugs-org severities &optional packages archivedp suppress tags

These commands retrieve bug reports from the GNU Debbugs server. debbugs-gnu returns a tabulated list, and debbugs-org returns a list of TODO items in org-mode. In order not to stress the GNU Debbugs server, the bugs are retrieved in chunks of 500 bugs. However, the bug report buffer shows all retrieved bugs then, in reverse bug number order.

severities is a list of strings which filter for the severities of the bugs to be retrieved. Valid severities are "serious", "important", "normal", "minor" and "wishlist" (see also the constant debbugs-gnu-all-severities). If the list is empty, there is no filtering with respect to severities. The keyword "tagged", which is also possible, is not a severity in the GNU Debbugs server but allows restricting the result to bugs with a given user tag.

packages, also a list of strings, points to the defined software packages on the GNU Debbugs server which should be taken into account. The existing package names are compiled into the constant debbugs-gnu-all-packages.

archivedp, if non-nil, extends the retrieval to also apply to archived bugs on the GNU Debbugs server.

When suppress is non-nil, closed bugs are suppressed from being retrieved from the Debbugs server. Which bugs are regarded as suppressed is configured via the user option debbugs-gnu-suppress-bugs. By default bugs marked as "done" are suppressed from being retrieved.

When severities contains the severity "tagged", tags is consulted in order to restrict the result to bugs which are tagged with one of the strings of the list tags. This list can also be empty; in this case locally tagged bugs are included in the results.

When called interactively, the commands require just the severities and the tags (if severities includes "tagged"). In order to provide the other arguments interactively, the commands must be called with a prefix, like C-u M-x debbugs-gnu. In the minibuffer, lists must be entered separated by commas.

Default values for interactive use can be configured with the user options debbugs-gnu-default-severities and debbugs-gnu-default-packages.

Presenting Bugs for the presentation of the results.

Command: debbugs-gnu-package &optional packages

This command shows all bugs for a given list of packages, sorted by severity and whether already resolved. It is debbugs-gnu-default-packages per default.

If the package "emacs" is member of the packages list, also all unresolved bugs for the next Emacs release are shown, like debbugs-gnu-emacs-release-blocking-reports does (see below).

Presenting Bugs for the presentation of the results.

Command: debbugs-gnu-bugs &rest bugs
Command: debbugs-org-bugs &rest bugs

The commands debbugs-gnu-bugs and debbugs-org-bugs show bugs specified by their bug number. Interactively, the bug numbers must be entered as a comma-separated list of bugs or bug ranges.

A bug range has the form ‘12345-21345’ or ‘-123’. In the former case, all bugs from 12345 until 21345 are presented, and in the latter case the last 123 bugs are shown, counting from the highest bug number in the repository.

A default value for interactive use can be configured in the user option debbugs-gnu-default-bug-number-list.

Presenting Bugs for the presentation of the results.

Command: debbugs-gnu-patches
Command: debbugs-org-patches

The commands debbugs-gnu-patches and debbugs-org-patches show all unarchived bugs of the packages declared in debbugs-gnu-default-packages, and tagged with "patch". This is useful for bug triaging.

Presenting Bugs for the presentation of the results.

Command: debbugs-gnu-tagged
Command: debbugs-org-tagged

The commands debbugs-gnu-tagged and debbugs-org-tagged show all bugs tagged locally. This list is useful for keeping track of bugs you are currently working on.

Presenting Bugs for the presentation of the results.

Command: debbugs-gnu-my-open-bugs
Command: debbugs-org-my-open-bugs

It is a good idea to maintain and eventually close your open bug reports. The functions debbugs-gnu-my-open-bugs and debbugs-org-my-open-bugs help you do this, by retrieving open bug reports, in which you are the submitter. These functions assume that you have defined the variable user-mail-address (see (emacs)Mail Headers).

Command: debbugs-gnu-emacs-release-blocking-reports &optional release
Command: debbugs-org-emacs-release-blocking-reports &optional release

The package "emacs" has the additional commands debbugs-gnu-emacs-release-blocking-reports and debbugs-org-emacs-release-blocking-reports, which show all blocking bugs for a given Emacs release. The user option debbugs-gnu-emacs-current-release contains the release number the blocking reports are selected for; a prefix argument allows to change this when called interactively.

User Option: debbugs-show-progress

If this user option is non-nil, a progress report is shown when retrieving bugs, defaults to t.


Next: , Previous: , Up: Top   [Contents][Index]

2 Searching in the Debbugs Database

The GNU Debbugs server allows searching the text of the messages submitted to the bugs in the database. It uses a HyperEstraier based search engine1.

The search engine uses an index over the bug database. This index is refreshed daily; search hits may not include recent changes made the same day.

Command: debbugs-gnu-search
Command: debbugs-org-search

Both these commands are completely interactive. They ask for a "search phrase" for the text search. It is just a string which contains the words to be searched for followed by each other. If there are operators like "AND", "ANDNOT" and "OR" between the words, the search happens for words at different positions in the text. Only complete words, contained in a message body, are searched for.

Wildcard searches are also supported. It can be used for forward match search and backward match search of words. For example, "[BW] euro" matches words which begin with "euro". "[EW] sphere" matches words which end with "sphere". Moreover, regular expressions are also supported. For example, "[RX] ^inter.*al$" matches words which begin with "inter" and end with "al".2 Several wildcards must be separated by the operators explained above.

While the words to be searched for are case insensitive, the operators must be specified in upper case.

While the search for the phrase is performed only in the bodies of the messages belonging to a bug report, it is also possible to restrict the search using further bug attributes. The commands ask for such attribute-value pairs, until an empty attribute is returned. Possible attributes are

severity

A comma-separated list of bug severities, See Retrieving Bugs.

package

A comma-separated list of defined software packages on the GNU Debbugs server, See Retrieving Bugs.

tags

A comma-separated list of defined user tags.

author

The email address of a message originator.

date

A time period during which the bug has been submitted or modified.

subject

Word(s) contained in the subject of the bug report.

status

The status of the bug report. Valid values are "pending", "forwarded", "fixed" and "done".

It is also possible to apply these commands with an empty search phrase. In this case, the GNU Debbugs server is searched only for bugs which match the given attributes. The attributes to be applied are the same as already described, plus

status

The status of the bug report. Valid values are "open", "forwarded" and "done". These values are different to the ones when there is a search phrase.

archive

Whether archived bugs shall be searched (no value to be entered).

src

Bugs which belong to a given source, if that attribute is set.

tag

An arbitrary string the bug is annotated with. Usually, this is the same as the status mentioned above.

owner
submitter
maint
correspondent

The email address of the bug’s owner, submitter, maintainer, or correspondent (somebody who has participated in bug messages).

log_modified
last_modified
found_date
fixed_date

The date of the last update, or the date of the bug report / bug fix.

unarchived

The date the bug was unarchived, if ever.

done

The email address of the worker who closed the bug (if done).

forwarded

A URL or an email address.

msgid

The message id of the initial bug report.

summary

The summary of the bug report.

Not all of these attributes can be queried on the GNU Debbugs server via the Debbugs/SOAP backend. In this case, the results of a query are filtered on the client side, which is indicated by the string "(client-side filter)" in the minibuffer after the attribute name. Note, that client side filters perform badly, because they can be applied only after all bugs have been downloaded.

These commands show also a progress report when debbugs-show-progress is non-nil.

Command: debbugs-gnu-guix-search
Command: debbugs-org-guix-search

By default, debbugs-gnu-search and debbugs-org-search search for all open bugs in the debbugs database. While this extensive search is laudable, it is perhaps not efficient. These two functions will let you search for only open guix bugs and patches.


Next: , Previous: , Up: Top   [Contents][Index]

3 Presenting Bugs

The commands described in the previous chapters generate (a) report buffer(s) applicable for navigation. debbugs-gnu-* displays a tabulated list, and debbugs-org-* displays a list of TODO items in org-mode.


Next: , Up: Presenting Bugs   [Contents][Index]

3.1 Tabulated Lists

A tabulated list of bug reports consisting of four columns for every bug entry: Id (the bug number), State (some bug attributes), Submitter (the name of the bug submitter), and Title (the bug subject). By default the bugs are sorted descending by Id; this can be changed by clicking in the headline.

Different foreground colors represent further information on the bug report. If the bug number uses a red color (debbugs-gnu-tagged), the bug has been tagged locally. The same face is used to mark bugs in the submitter or title column, when the bug has been reported / is maintained by the user.

The bug state can appear in different colors: red (debbugs-gnu-new, nobody has answered this bug yet), ForestGreen (debbugs-gnu-handled, the bug has been modified recently), MidnightBlue (debbugs-gnu-pending, the bug is pending), orange (debbugs-gnu-stale, the bug has not been touched for a while), and DarkGrey (debbugs-gnu-done, the bug is closed). Archived bugs are shown with inverse face (debbugs-gnu-archived).

A DarkGrey background color (debbugs-gnu-marked) in the title column shows bugs which have been marked locally.

The minor mode debbugs-gnu-mode is active in bug report buffers. This enables the following key strokes:

RET
mouse-1
mouse-2
debbugs-gnu-select-report
Show the email messages that discuss the bug.
Adebbugs-gnu-select-current-bugs
Show the email messages for all currently displayed messages (including merged reports). Limited by user option debbugs-gnu-select-bugs-limit.
ddebbugs-gnu-display-status
Show all bug attributes.
/debbugs-gnu-narrow-to-status
Narrow the list of bugs to the bugs that match the given regex in State, Submitter or Title. With a prefix argument C-u, the list of bugs is narrowed to a match in State only.
Rdebbugs-gnu-show-all-blocking-reports
Narrow the list of bug reports to the ones that are blocking the current Emacs release, as specified in ‘debbugs-gnu-emacs-current-release’. With a prefix argument C-u, the current Emacs release is read from the minibuffer.
wdebbugs-gnu-widen
Restore the full list again after narrowing.
gdebbugs-gnu-rescan
Reload all bugs. With a prefix argument C-u, the bug status cache is disabled, and all bug reports are retrieved from the GNU Debbugs server.
B
b
debbugs-gnu-show-blocking-reports
debbugs-gnu-show-blocked-by-reports
Show all bug reports which are blocking / blocked by this bug.
sdebbugs-gnu-toggle-sort
Toggle sorting order of bugs.
tdebbugs-gnu-toggle-tag
Toggle local tag of bugs.
mdebbugs-gnu-toggle-mark
Toggle local mark of bugs.
xdebbugs-gnu-toggle-suppress
Toggle showing of closed bugs.
Cdebbugs-gnu-send-control-message
Send a control message for this bug, Control Messages.
Edebbugs-gnu-make-control-message
Make (but don’t send) a control message for this bug, Control Messages.

Tagging a bug locally via t is an efficient way to keep bugs visible you are working on. The command debbugs-gnu-tagged shows all locally tagged bugs in a list.

Marking a bug locally via m is meant for single sessions. This is a mean to mark bugs for different reasons, like marking a bug in a list you have processed already during a bug triage.

Both tagged and marked bugs are kept persistent in the file debbugs-gnu-persistency-file.

The user option debbugs-gnu-suppress-closed controls whether closed bugs are shown in the initial list.

The user option debbugs-gnu-mail-backend controls the presentation of email messages produced by typing RET or by clicking the mouse on a bug: if its value is gnus, the default, a GNUS ephemeral group for that bug will be shown; if its value is rmail, the command will present an Rmail folder instead.


Next: , Previous: , Up: Presenting Bugs   [Contents][Index]

3.2 TODO Items

TODO items are offered as usual in org-mode. The bug attributes are mapped onto properties of these items. They can be shown by the usual navigation in org-mode.

Bug severities are mapped onto org severities, see debbugs-org-severity-priority.

The minor mode debbugs-org-mode is active in bug report buffers. This enables the following key strokes:

TABorg-cycle
Outline the bug report attributes in org-mode.
C-c # ddebbugs-gnu-display-status
Show all bug attributes.
C-c # tdebbugs-gnu-toggle-tag
Toggle local tag of bugs.
C-c # mdebbugs-gnu-toggle-mark
Toggle local mark of bugs.
C-c # Cdebbugs-gnu-send-control-message
Send a control message for this bug, Control Messages.
C-c # Edebbugs-gnu-make-control-message
Make (but don’t send) a control message for this bug, Control Messages.

When the bug attributes are shown by org-cycle, there is a link Messages which opens the messages for that bug. The user options debbugs-gnu-suppress-closed and debbugs-gnu-mail-backend have the same meaning as in Tabulated Lists.


Next: , Previous: , Up: Presenting Bugs   [Contents][Index]

3.3 Control Messages

Debbugs control messages are sent by email to the GNU Debbugs control server. Their format is described in https://debbugs.gnu.org/server-control.html.

A control message can be initiated in the tabulated list of bugs, in the list of org TODO items, or in the GNUS ephemeral group or Rmail folder opened for the messages belonging to a given bug. Control messages can be sent to unarchived bugs only, in case a bug is archived the control message ‘unarchive’ must be sent first.

In the minibuffer, the following control messages can be requested (assuming that 12345 is the bug the control message is intended for). The strings show the exact format of the control messages. For the meaning of the control messages, See Mail Command Index.

block
unblock

"block|unblock 12345 by 54321"

The second bug number is read interactively. It could be also a list of comma-separated bug numbers.

close
done

"close 12345 25.1"

The second argument, the Emacs version, is read interactively if the bug belongs to the "emacs" package.

confirmed
easy
help
moreinfo
notabug
patch
pending
security
unreproducible
wontfix

"tags 12345 confirmed|easy|help|moreinfo|notabug"

"tags 12345 patch|pending|security|unreproducible|wontfix"

If the command invoking the control message has been prefixed with C-u, the respective tag is removed from the bug, like

"tags 12345 - confirmed"

donenotabug
doneunreproducible
donewontfix

"tags 12345 notabug|unreproducible|wontfix"
"close 12345 25.1"

The second argument in the close message, the Emacs version, is read interactively if the bug belongs to the "emacs" package.

found
notfound
fixed
notfixed

"found|notfound|fixed|notfixed 12345 25.1"

The second argument, the Emacs version, is read interactively if the bug belongs to the "emacs" package.

forwarded

"forwarded 12345 address"

The address, an email address or a URL, is read interactively.

forcemerge
merge

"forcemerge|merge 12345 54321"

The second bug number is read interactively. It can be also a list of comma-separated bug numbers.

invalid

"tags 12345 notabug"
"tags 12345 wontfix"
"close 12345"

noowner
notforwarded

"noowner|notforwarded 12345"

owner

"owner 12345 !"

reassign

"reassign 12345 package"

The comma-separated package names on the GNU Debbugs server are read interactively. Reassigning to the pseudo package "spam" let the bug disappear from the bug database.

reopen

"reopen 12345"

retitle

"retitle 12345 title"

The new bug title is read interactively.

serious
important
normal
minor
wishlist

"severity 12345 serious|important|normal|minor|wishlist"

unarchive

"unarchive 12345"

unmerge

"unmerge 12345"

usertag

"user username"
"usertag 12345 tag"

The username, read interactively, is either a package name or an email address. The tag to be set is also read interactively.

documentation

"user emacs"
"usertag 12345 documentation"

How the control messages are sent is controlled by the debbugs-gnu-send-mail-function user option. If it is nil (the default value), the value of send-mail-function is used. This could be inconvenient, for example when an external interactive mail client is configured.


Next: , Previous: , Up: Presenting Bugs   [Contents][Index]

3.4 Applying Patches in the Emacs Repository

Several bugs carry a proposed patch in one of their messages. Usually, those bugs are marked with the with "patch" tag. Retrieving Bugs how to show such bugs.

If a GNUS ephemeral group for such a bug is opened, it is possible to apply the patch directly to the Emacs repository. Move the cursor to the message containing a patch, and hit M-m. It determines whether one or several patches are in the MIME attachments or just included in the message, applies them, runs make -k in the lisp subdirectory, and shows a ‘*vc-dir*’ buffer of the Emacs repository with the changed file(s).

The Emacs repository is determined via the user options debbugs-gnu-trunk-directory or debbugs-gnu-branch-directory. The latter one is used, when the patch is applied with the prefixed command C-u M-m. If the predefined directory does not point to an existing path, it is read from the minibuffer.

A further M-m in the corresponding ‘*vc-diff*’ buffer opens the modified file. Here you can apply M-m again. This creates a ChangeLog entry with all needed information. A final M-m in the ‘ChangeLog’ buffer commits the patch via ‘*vc-log*’.


Previous: , Up: Presenting Bugs   [Contents][Index]

3.5 Posting Patches to Debbugs from the Emacs Repository

Once you have committed a patch locally to fix a bug you usually want to post it to the bug thread for review and testing. And when the patch is deemed satisfactory and pushed to the official repository, the bug should be marked closed.

The query for commit (or commit range) to use is controlled by debbugs-gnu-read-commit-range-hook. Initially it has an entry which operates in ‘*vc-change-log*’ buffers, but additional entries may be added to give sensible results for other modes that work with git.

The command debbugs-gnu-pick-commits (bound to c in *vc-change-log* buffers by default) helps automate both these processes: it queries for a commit (or commit range), and a bug number (defaulting to the bug number mentioned in the commit message). It then jumps you to a buffer associated with the bug. When you reply to a message in the bug thread, you are asked whether to post the commits as patches (optionally tagging the bug with "patch"), or announce that the bug has been fixed by the selected commits (optionally closing the bug and marking as closed in the Emacs version corresponding to the patch).

For example, suppose you are reading the message of “Bug#12345: foo-mode fails to call frobnicate on startup” in a message buffer. You decide to fix it, so you switch to the source code, add in the missing call and commit locally, with the commit message “* lisp/foo-mode.el (foo-mode): Call frobnicate (Bug#12345).” Use C-x v l to run vc-print-log, and navigate to the new commit. Press c and then RET to accept the default bug number (which will be 12345 since it’s in the commit message) in response to the prompt. You are then popped to the message buffer, and when you reply to the message, press p to post the git formatted patch as an attachment for review, and then answer y to tag the bug with "patch" when the message is sent. Assuming you get favorable reviews, you then push it, and again hit c but this time press a (for “announce”) after replying to the relevant bug thread message. This will insert some text describing the commit and where it was pushed to, and answering y will arrange for the bug to be closed when the message is sent.

3.5.1 Customizing debbugs-gnu-pick-commits

The string inserted to describe an announced commit is controlled by the user option debbugs-gnu-commit-description-format, it is a format string passed to the --format argument of git show. Additionally, if the remote url matches an entry in debbugs-gnu-git-remote-info-alist, then its commit-url subitem is appended to the commit description. By default this user option is configured for the GNU Emacs and GNU ELPA repositories, more entries may be added to work with other repositories of other packages.


Next: , Previous: , Up: Top   [Contents][Index]

4 Minor Mode

Emacs uses bug-reference.el for adding hyperlinks to bugs in files like ChangeLog, or in commentary sections of other files. The reference to such bugs have a specialized format, Bug#12345. The hyperlinks are implemented as minor modes bug-reference-mode and bug-reference-prog-mode.

This package adds a new minor mode debbugs-browse-mode on top of them. Instead of using the default built-in Emacs browser for a given bug reference, it opens a corresponding bug report buffer. The user option debbugs-browse-function controls, whether debbugs-gnu-bugs or debbugs-org-bugs is called.

This minor mode is applicable for all URLs, not only bug references. Any URL with the format https://debbugs.gnu.org/12345 or https://bugs.gnu.org/54321 will be shown in a bug report buffer, when debbugs-browse-mode is enabled. See user option debbugs-browse-url-regexp for the syntax of supported URLs.

In order to enable it globally, you can add the following forms to your ~/.emacs:

(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode)
(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)

If you want to enable this in GNUS summary and GNUS article buffers, you might set:

(add-hook 'gnus-summary-mode-hook 'bug-reference-mode)
(add-hook 'gnus-article-mode-hook 'bug-reference-mode)

Next: , Previous: , Up: Top   [Contents][Index]

Command Index

Jump to:   D  
Index Entry  Section

D
debbugs-browse-mode: Minor Mode
debbugs-gnu: Retrieving Bugs
debbugs-gnu-bugs: Retrieving Bugs
debbugs-gnu-emacs-release-blocking-reports: Retrieving Bugs
debbugs-gnu-guix-search: Searching Bugs
debbugs-gnu-my-open-bugs: Retrieving Bugs
debbugs-gnu-package: Retrieving Bugs
debbugs-gnu-patches: Retrieving Bugs
debbugs-gnu-pick-commits: Posting Patches
debbugs-gnu-search: Searching Bugs
debbugs-gnu-tagged: Retrieving Bugs
debbugs-org: Retrieving Bugs
debbugs-org-bugs: Retrieving Bugs
debbugs-org-emacs-release-blocking-reports: Retrieving Bugs
debbugs-org-guix-search: Searching Bugs
debbugs-org-my-open-bugs: Retrieving Bugs
debbugs-org-patches: Retrieving Bugs
debbugs-org-search: Searching Bugs
debbugs-org-tagged: Retrieving Bugs

Jump to:   D  

Next: , Previous: , Up: Top   [Contents][Index]

Variable Index

Jump to:   D  
Index Entry  Section

D
debbugs-browse-function: Minor Mode
debbugs-gnu-all-packages: Retrieving Bugs
debbugs-gnu-all-severities: Retrieving Bugs
debbugs-gnu-branch-directory: Applying Patches
debbugs-gnu-commit-description-format: Posting Patches
debbugs-gnu-default-bug-number-list: Retrieving Bugs
debbugs-gnu-default-packages: Retrieving Bugs
debbugs-gnu-default-severities: Retrieving Bugs
debbugs-gnu-default-suppress-bugs: Retrieving Bugs
debbugs-gnu-git-remote-info-alist: Posting Patches
debbugs-gnu-mail-backend: Tabulated Lists
debbugs-gnu-persistency-file: Tabulated Lists
debbugs-gnu-read-commit-range-hook: Posting Patches
debbugs-gnu-send-mail-function: Control Messages
debbugs-gnu-suppress-closed: Tabulated Lists
debbugs-gnu-trunk-directory: Applying Patches
debbugs-org-severity-priority: TODO Items
debbugs-show-progress: Retrieving Bugs

Jump to:   D  

Next: , Previous: , Up: Top   [Contents][Index]

Key Index

Jump to:   /  
A   B   C   D   E   G   M   R   S   T   W   X  
Index Entry  Section

/
/: Tabulated Lists

A
A: Tabulated Lists

B
B: Tabulated Lists
b: Tabulated Lists

C
C: Tabulated Lists
C-c # C: TODO Items
C-c # d: TODO Items
C-c # E: TODO Items
C-c # m: TODO Items
C-c # t: TODO Items

D
d: Tabulated Lists

E
E: Tabulated Lists

G
g: Tabulated Lists

M
m: Tabulated Lists
M-m: Applying Patches
mouse-1: Tabulated Lists
mouse-2: Tabulated Lists

R
R: Tabulated Lists
RET: Tabulated Lists
RET: Tabulated Lists

S
s: Tabulated Lists

T
t: Tabulated Lists
TAB: TODO Items

W
w: Tabulated Lists

X
x: Tabulated Lists

Jump to:   /  
A   B   C   D   E   G   M   R   S   T   W   X  

Previous: , Up: Top   [Contents][Index]

Debbugs control mailserver commands

reassign bugnumber package [ version ]

Records that bug #bugnumber is a bug 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 bug tracking system will note that the bug affects that version of the newly-assigned package.

You can assign a bug to two packages at once by separating the package names with a comma. However, you should only do this if the bug can be fixed by a change to either package. If this is not the case, you should clone the bug and reassign the clone to the other 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 bug is not closed then reopen won’t do anything, not even change the originator. To change the originator of an open bug report, use the submitter command; note that this will inform the original submitter of the change.

If the bug 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 bug tracking system uses this information, in conjunction with fixed versions recorded when closing bugs, to display lists of bugs open in various versions of each package. It considers a bug 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 bug 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 bug at that version in that the bug 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 bug was found.

fixed bugnumber version

Indicate that bug #bugnumber was fixed in the given version of the package to which it is assigned. version may be a fully qualified version, of the form sourcepackagename/version.

This does not cause the bug to be marked as closed, it merely adds another version in which the bug was fixed. Use the bugnumber-done address to close a bug and mark it fixed in a particular version.

notfixed bugnumber version

Remove the record that bug #bugnumber has been fixed in the given version. version may be a fully qualified version, of the form sourcepackagename/version.

This command is equivalent to found followed by notfound (the found removes the fixed at a particular version, and notfound removes the found) with the exception that the bug is not reopened if the found version is greater than any existing fixed version. It is intended for fixing mistakes in the record of when a bug was fixed; in most cases, you actually want found, not notfixed.

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 bug that wasn’t previously noted as having been forwarded. address should generally be a URI, or possibly an email address. Using a URI where possible allows tools to query a remote bug tracking system (such as bugzilla) for a bug’s status.

Example usage:

forwarded 12345 https://bugz.illa.foo/cgi/54321
notforwarded bugnumber

Forgets any idea that bugnumber has been forwarded to any upstream maintainer. If the bug was not recorded as having been forwarded then this will do nothing.

retitle bugnumber new-title

Changes the title of a bug report to that specified (the default is the Subject mail header from the original report).

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

severity bugnumber severity

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

Severities are serious, important, normal, minor, wishlist.

For their meanings please consult the general developers’ documentation for the bug system.

clone bugnumber NewID [ new IDs … ]

The clone control command allows you to duplicate a bug report. It is useful in the case where a single report actually indicates that multiple distinct bugs have occurred. "New IDs" are negative numbers, separated by spaces, which may be used in subsequent control commands to refer to the newly duplicated bugs. 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 bug reports. When reports are merged opening, closing, marking or unmarking as forwarded and reassigning any of the bugs to a new package will have an identical effect on all of the merged reports.

Before bugs 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 bug 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 bugs listed in a merge command is already merged with another bug 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 bugs.

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 bug reports. The first bug is chosen as the master bug, and its settings are assigned to the bugs listed next in the command. See the text above for a description of what merging means.

Note that this makes it possible to close bugs by merging; you are responsible for notifying submitters with an appropriate close message if you do this.

unmerge bugnumber

Disconnects a bug 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 bug explicitly named are removed.

If many bug 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 bug simply include several unmerge commands in your message.

tags bugnumber [ + | - | = ] tag [ tag … ]

Sets tags for the bug report #bugnumber. No notification is sent to the user who reported the bug. 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, notabug and easy.

For their meanings please consult the general developers’ documentation for the bug system.

block bugnumber by bug [ bug … ]
unblock bugnumber by 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 bug report #bugnumber.

A notification is sent to the user who reported the bug, but (in contrast to mailing bugnumber-done) the text of the mail which caused the bug 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 bug knows why it is being closed. The use of this command is therefore deprecated.

If you supply a fixed-version, the bug tracking system will note that the bug 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 bug 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 bug yourself, you can use the ! shorthand or specify your own email address.

noowner bugnumber

Forgets any idea that the bug has an owner other than the usual maintainer. If the bug had no owner recorded then this will do nothing.

archive bugnumber

Archives a bug that was previously archived if the bug fulfills the requirements for archival, ignoring time.

unarchive bugnumber

Unarchives a bug 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.


Footnotes

(1)

This has been added to the Debbugs/SOAP backend of the GNU Debbugs server only.

(2)

Simplified forms, as described in the Hyperestraier User Guide, are not supported.