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

This is debbugs-ug.info, produced by makeinfo version 5.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 to results are presented.

* 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: Command Index,  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).

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

'<RET>'       'debbugs-gnu-select-report'
'<mouse-1>'   Open a GNUS ephemeral group for that bug.
'<mouse-2>'   
              
'd'           'debbugs-gnu-display-status'
              Show all bug attributes.
              
'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::.
              

\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 opened for
the messages belonging to a given bug.  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: Command Index,  Next: Variable Index,  Prev: Layout,  Up: Top

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