[gnu-emacs-elpa] / packages / debbugs / debbugs-ug.info

This is debbugs-ug.info, produced by makeinfo version 6.0 from
debbugs-ug.texi.

Copyright (C) 2015 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.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Debbugs UG: (debbugs-ug).  Debbugs User Interface in Emacs.
END-INFO-DIR-ENTRY

\1f
File: debbugs-ug.info,  Node: Top,  Next: Retrieving Bugs,  Up: (dir)

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', *note
Org Mode: (org)Top.).  As backend they use the 'debbugs' Emacs library
(*note Debbugs Programmer's Manual: (debbugs)Top.).

* Menu:

* Retrieving Bugs::             How to retrieve bugs.
* Searching Bugs::              How to search in the debbugs database.
* Layout::                      How the results are presented.
* Minor Mode::                  How to use browse bug URLs.

* Command Index::               Debbugs commands.
* Variable Index::              User options and variables.
* Key Index::                   Keyboard strokes on bug report buffers.

\1f
File: debbugs-ug.info,  Node: Retrieving Bugs,  Next: Searching Bugs,  Prev: Top,  Up: Top

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.

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

     *note 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.

     *note Layout:: for the presentation of the results.

\1f
File: debbugs-ug.info,  Node: Searching Bugs,  Next: Layout,  Prev: Retrieving Bugs,  Up: Top

2 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)(1).

 -- 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".(2)

     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, *Note Retrieving
          Bugs::.

     'package'
          A comma-separated list of defined software packages on the
          GNU Debbugs server, *Note 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.

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

\1f
File: debbugs-ug.info,  Node: Layout,  Next: Minor Mode,  Prev: Searching Bugs,  Up: Top

3 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'.

* Menu:

* Tabulated Lists::             Tabulated Lists.
* TODO Items::                  TODO Items.
* Control Messages::            Control Messages.

\1f
File: debbugs-ug.info,  Node: Tabulated Lists,  Next: TODO Items,  Up: Layout

3.1 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>'        'debbugs-gnu-select-report'
'<mouse-1>'    Show the email messages that discuss the bug.
'<mouse-2>'    
               
'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'            'debbugs-gnu-show-blocking-reports'
'b'            '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,
               *note 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.

\1f
File: debbugs-ug.info,  Node: TODO Items,  Next: Control Messages,  Prev: Tabulated Lists,  Up: Layout

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'.

   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, *note 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.

\1f
File: debbugs-ug.info,  Node: Control Messages,  Prev: TODO Items,  Up: Layout

3.3 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.

\1f
File: debbugs-ug.info,  Node: Minor Mode,  Next: Command Index,  Prev: Layout,  Up: Top

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

\1f
File: debbugs-ug.info,  Node: Command Index,  Next: Variable Index,  Prev: Minor Mode,  Up: Top

Command Index
*************