Copyright © 2015-2016 Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

     All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction.

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 mail 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 Mode (org)).  As backend they use the debbugs Emacs library (see Debbugs Programmer's Manual (debbugs)).

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.

 -- 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.  If there were more than debbugs-gnu-default-hits-per-page bug results from the query, there are widgets (debbugs-gnu) or links (debbugs-org) in the result buffer for retrieving the other results.

     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 to restrict the result to bugs with a given user tag.

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

     ARCHIVEDP, if non-nil, extends the result also on archived bugs on the GNU Debbugs server.

     SUPPRESS shall also distinct between nil and non-nil.  When non-nil, closed bugs are suppressed from the results.

     When SEVERITIES contains the severity "tagged", TAGS is consulted in order to restrict the result on 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 into the results.

     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 comma-separated.

     Default values for interactive use could be configured in the customer options debbugs-gnu-default-severities and debbugs-gnu-default-packages.

     When the result would exceed more than 500 bugs, the user is asked how many bugs to retrieve at once.  This value can be configured in the customer option debbugs-gnu-default-hits-per-page.  However, it is not recommended to exceeds the default value.

     Layout 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 comma-separated list.

     Layout for the presentation of the results.

Searching in the Debbugs Database.
**********************************

The GNU Debbugs server allows full text search in the database.  It uses a HyperEstraier based search engine (http://fallabs.com/hyperestraier/uguide-en.html#searchcond) (This has been added to the Debbugs/SOAP backend of the GNU Debbugs server only.).

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

     These both commands are completely interactive.  They ask for a "search phrase" for the full text search.  It is just a string which contains the words to be searched for, combined by operators like AND, ANDNOT and OR.  If there is no operator between the words, AND is used by default.

     Wild card searches are also supported.  It can be used for forward match search and backward match search.  For example, "[BW] euro" matches words which begin with "euro".  "[EW] shere" 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". (Simplified forms, as described in the Hyperestraier User Guide, are not supported.)

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

     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 discriminate the search to further bug attributes.  The commands ask for such key-value pairs, until an empty key 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.

     submitter
          The address of the bug submitter.

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

     subject
          Word(s) the subject of the bug report contains.

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

     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 fulfill the given attributes.  The attributes to be applied are the same as already described, plus

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

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

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

     owner
     maint
     correspondent
          The email address of the bug's owner, 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 has been unarchived, if ever.

     done
          The email address of the worker who has 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 could be queried on the GNU Debbugs server via the Debbugs/SOAP backend.  In this case, the results of a query are discriminated on the client side, which is indicated by the string "(client-side filter)" in the minibuffer after the attribute name.

Layout
******

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

Tabulated Lists
===============

A tabulated list of bug reports consist 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).  Per default the bugs are sorted by Id; this could be changed by clicking in the headline.

Per bug retrieval only up to 500 (debbugs-gnu-default-hits-per-page) bugs are retrieved and presented in a buffer.  If there shall be presented more bugs, widgets are placed on the top and bottom of the buffer for navigation to further report buffers.

Different foreground colours present further information on the bug report.  If the bug number uses a red colour (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 could appear in different colours: red (debbugs-gnu-new, nobody has answered yet to this bug), 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).

The bug report buffers have enabled the minor debbugs-gnu-mode.  This enables the following key strokes:

RET

mouse-1

mouse-2
debbugs-gnu-select-report

Show the email messages that discuss the bug.

d
debbugs-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.

R
debbugs-gnu-show-all-blocking-reports

Narrow the list of bug reports to the ones that are blocking the
current release.

w
debbugs-gnu-widen

Restore the full list again after narrowing.

g
debbugs-gnu-rescan

Reload all bugs 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.

s
debbugs-gnu-toggle-sort

Toggle sorting order of bugs.

t
debbugs-gnu-toggle-tag

Toggle local tag of bugs.

x
debbugs-gnu-toggle-suppress

Toggle showing of closed bugs.

C
debbugs-gnu-send-control-message

Send a control message for this bug, Control Messages.

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.

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.

Per bug retrieval only up to 500 (debbugs-gnu-default-hits-per-page) bugs are retrieved and presented in a buffer.  At the end of the buffer there is a link, which allows to append the next 500 bugs to the list.

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

The bug report buffers have enabled the minor debbugs-gnu-mode.  This enables the following key strokes:

TAB
org-cycle

Outline the bug report attributes in org-mode.

C-c # d
debbugs-gnu-display-status

Show all bug attributes.

C-c # t
debbugs-gnu-toggle-tag

Toggle local tag of bugs.

C-c # C
debbugs-gnu-send-control-message

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 a GNUS ephemeral group for that bug. (see xxx).

Control Messages
================

Debbugs control messages are sent by email to the GNU Debbugs control server.  Their format is described in http://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.

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
     "close 12345 25.1"

     The second argument, the Emacs version, is read interactively.

confirmed
fixed
help
moreinfo
notabug
patch
pending
security
unreproducible
wontfix
     "tags 12345 confirmed|fixed|help|moreinfo|notabug"

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

done
donenotabug
doneunreproducible
donewontfix
     "tags 12345 fixed|notabug|unreproducible|wontfix"

     "close 12345 25.1"

     The second argument in the close message, the Emacs version, is read interactively.

forcemerge
merge
     "forcemerge|merge 12345 54321"

     The second bug number is read interactively.

important
minor

normal
serious

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

invalid
     "tags 12345 notabug"

     "tags 12345 wontfix"

     "close 12345"

noowner
     "noowner 12345"

owner
     "owner 12345 !"

reassign
     "reassign 12345 PACKAGE"

     The package name on the GNU Debbugs server is read interactively.

reopen
     "reopen 12345"

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.

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 customer 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 http://debbugs.gnu.org/12345 will be shown in a bug report buffer, when debbugs-browse-mode is enabled.