Make debbugs-newest-bugs more robust

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

\input texinfo
@setfilename debbugs-ug.info
@settitle Debbugs User Guide

@dircategory Emacs
@direntry
* Debbugs UG: (debbugs-ug).  Debbugs User Interface in Emacs.
@end direntry

@copying
Copyright @copyright{} 2015-2016 Free Software Foundation, Inc.

@quotation
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.
@end quotation
@end copying

@titlepage
@title Debbugs User Guide
@author by Michael Albinus
@page
@insertcopying
@end titlepage

@contents


@node Top
@top 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
(@code{debbugs-gnu}) or as @code{org-mode} TODO list
(@code{debbugs-org}, @pxref{Top, , Org Mode, org}).  As backend they
use the @code{debbugs} Emacs library (@pxref{Top, , Debbugs
Programmer's Manual, debbugs}).

@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.
@end menu


@node Retrieving Bugs
@chapter Retrieving Bugs

Bugs are retrieved by the @code{debbugs-gnu} or @code{debbugs-org}
commands.  In their simple version, they retrieve just bugs for the
@code{"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
@code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} are applicable.


@deffn  {Command} debbugs-gnu severities &optional packages archivedp suppress tags
@deffnx {Command} debbugs-org severities &optional packages archivedp suppress tags

These commands retrieve bug reports from the GNU Debbugs server.
@code{debbugs-gnu} returns a tabulated list, and @code{debbugs-org}
returns a list of TODO items in @code{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.

@vindex debbugs-gnu-all-severities
@var{severities} is a list of strings which filter for the severities
of the bugs to be retrieved.  Valid severities are @code{"serious"},
@code{"important"}, @code{"normal"}, @code{"minor"} and
@code{"wishlist"} (see also the constant
@code{debbugs-gnu-all-severities}).  If the list is empty, there is no
filtering with respect to severities.  The keyword @code{"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.

@vindex debbugs-gnu-all-packages
@var{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
@code{debbugs-gnu-all-packages}.

@var{archivedp}, if non-@code{nil}, extends the result also on
archived bugs on the GNU Debbugs server.

@vindex debbugs-gnu-default-suppress-bugs
@var{suppress} shall also distinct between @code{nil} and
non-@code{nil}.  When non-@code{nil}, closed bugs are suppressed from
being retrieved from the Debbugs server.  Which bugs are regarded as
suppressed is configured in the customer option
@code{debbugs-gnu-suppress-bugs}.  Per default, bugs marked as
@code{"done"} are suppressed from being retrieved.

When @var{severities} contains the severity @code{"tagged"},
@var{tags} is consulted in order to restrict the result on bugs which
are tagged with one of the strings of the list @var{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 @var{severities}
and the @var{tags} (if @var{severities} includes @code{"tagged"}).  In
order to provide the other arguments interactively, the commands must
be called with a prefix, like @kbd{C-u M-x debbugs-gnu}.  In the
minibuffer, lists must be entered comma-separated.

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

@ref{Layout} for the presentation of the results.

@end deffn


@deffn  {Command} debbugs-gnu-bugs &rest bugs
@deffnx {Command} debbugs-org-bugs &rest bugs

The commands @code{debbugs-gnu-bugs} and @code{debbugs-org-bugs} show
bugs specified by their bug number.  Interactively, the bug numbers
must be entered as comma-separated list.

@ref{Layout} for the presentation of the results.

@end deffn


@deffn  {Command} debbugs-gnu-patches
@deffnx {Command} debbugs-org-patches

The commands @code{debbugs-gnu-patches} and @code{debbugs-org-patches} show
all bugs tagged with @code{"patch"}.  This is useful for bug triages.

@ref{Layout} for the presentation of the results.

@end deffn


@node Searching Bugs
@chapter Searching in the Debbugs Database.

The GNU Debbugs server allows text search in the database in the
messages submitted to the bugs.  It uses a
@uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond,
HyperEstraier based search engine}@footnote{This has been added to the
Debbugs/SOAP backend of the GNU Debbugs server only.}.

@deffn  {Command} debbugs-gnu-search
@deffnx {Command} debbugs-org-search

These both commands are completely interactive.  They ask for a
@code{"search phrase"} for the 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.  Only complete words, contained in a message body,
are searched for.

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] 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".@footnote{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

@table @samp
@item severity
A comma-separated list of bug severities, @xref{Retrieving Bugs}.

@item package
A comma-separated list of defined software packages on the GNU Debbugs
server, @xref{Retrieving Bugs}.

@item tags
A comma-separated list of defined user tags.

@item author
The email address of a message originator.

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

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

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

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

@table @samp
@item archive
Whether archived bugs shall be searched (no value to be entered).

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

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

@item  owner
@itemx submitter
@itemx maint
@itemx correspondent
The email address of the bug's owner, submitter, maintainer, or
correspondent (somebody who has participated in bug messages).

@item  log_modified
@itemx last_modified
@itemx found_date
@itemx fixed_date
The date of the last update, or the date of the bug report / bug fix.

@item unarchived
The date the bug has been unarchived, if ever.

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

@item forwarded
A URL or an email address.

@item msgid
The message id of the initial bug report.

@item summary
The summary of the bug report.
@end table

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.
Note, that client side filters perform badly, because they could be
applied only after all bugs have been downloaded.
@end deffn


@node Layout
@chapter Layout

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

@menu
* Tabulated Lists::             Tabulated Lists.
* TODO Items::                  TODO Items.
* Control Messages::            Control Messages.
@end menu


@node Tabulated Lists
@section Tabulated Lists

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

Different foreground colours present further information on the bug
report.  If the bug number uses a red colour
(@code{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
(@code{debbugs-gnu-new}, nobody has answered yet to this bug),
ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
pending), orange (@code{debbugs-gnu-stale}, the bug has not been
touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
is closed).  Archived bugs are shown with inverse face
(@code{debbugs-gnu-archived}).

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

@multitable @columnfractions .20 .80

@item
@kindex @kbd{@key{RET}}
@kbd{@key{RET}} @*
@kindex @kbd{@key{mouse-1}}
@kbd{@key{mouse-1}} @*
@kindex @kbd{@key{mouse-2}}
@kbd{@key{mouse-2}} @tab
@code{debbugs-gnu-select-report} @*
Show the email messages that discuss the bug.

@* @item
@kindex @kbd{d}
@kbd{d} @tab
@code{debbugs-gnu-display-status} @*
Show all bug attributes.

@item
@kindex @kbd{/}
@kbd{/} @tab
@code{debbugs-gnu-narrow-to-status} @*
Narrow the list of bugs to the bugs that match the given regex in
@code{State}, @code{Submitter} or @code{Title}.

@item
@kindex @kbd{R}
@kbd{R} @tab
@code{debbugs-gnu-show-all-blocking-reports} @*
Narrow the list of bug reports to the ones that are blocking the
current release.

@item
@kindex @kbd{w}
@kbd{w} @tab
@code{debbugs-gnu-widen} @*
Restore the full list again after narrowing.

@item
@kindex @kbd{g}
@kbd{g} @tab
@code{debbugs-gnu-rescan} @*
Reload all bugs.  With a prefix argument @kbd{C-u}, the bug status
cache is disabled, and all bug reports are retrieved from the GNU
Debbugs server.

@item
@kindex @kbd{B}
@kbd{B} @*
@kindex @kbd{b}
@kbd{b} @tab
@code{debbugs-gnu-show-blocking-reports} @*
@code{debbugs-gnu-show-blocked-by-reports} @*
Show all bug reports which are blocking / blocked by this bug.

@item
@kindex @kbd{s}
@kbd{s} @tab
@code{debbugs-gnu-toggle-sort} @*
Toggle sorting order of bugs.

@item
@kindex @kbd{t}
@kbd{t} @tab
@code{debbugs-gnu-toggle-tag} @*
Toggle local tag of bugs.

@item
@kindex @kbd{x}
@kbd{x} @tab
@code{debbugs-gnu-toggle-suppress} @*
Toggle showing of closed bugs.

@item
@kindex @kbd{C}
@kbd{C} @tab
@code{debbugs-gnu-send-control-message} @*
Send a control message for this bug, @ref{Control Messages}.

@end multitable

@vindex debbugs-gnu-suppress-closed
The user option @code{debbugs-gnu-suppress-closed} controls, whether
closed bugs are shown in the initial list.

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


@node TODO Items
@section TODO Items

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

Bug severities are mapped onto org severities, see
@code{debbugs-org-severity-priority}.

The bug report buffers have enabled the minor
@code{debbugs-org-mode}.  This enables the following key strokes:

@multitable {@kbd{C-c # C}} {Some very very very long long text Some very very very long long text Some very very very long long text}

@item
@kindex @kbd{@key{TAB}}
@kbd{@key{TAB}} @tab
@code{org-cycle} @*
Outline the bug report attributes in @code{org-mode}.

@item
@kindex @kbd{C-c # d}
@kbd{C-c # d} @tab
@code{debbugs-gnu-display-status} @*
Show all bug attributes.

@item
@kindex @kbd{C-c # t}
@kbd{C-c # t} @tab
@code{debbugs-gnu-toggle-tag} @*
Toggle local tag of bugs.

@item
@kindex @kbd{C-c # C}
@kbd{C-c # C} @tab
@code{debbugs-gnu-send-control-message} @*
Send a control message for this bug, @ref{Control Messages}.

@end multitable

When the bug attributes are shown by @code{org-cycle}, there is a link
@code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).


@node Control Messages
@section Control Messages

Debbugs control messages are sent by email to the GNU Debbugs control
server.  Their format is described in
@uref{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 @samp{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.

@table @samp
@item block
@itemx unblock
"block|unblock 12345 by 54321"

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

@item close
"close 12345 25.1"

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

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

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

@item done
@itemx donenotabug
@itemx doneunreproducible
@itemx donewontfix
"tags 12345 fixed|notabug|unreproducible|wontfix" @*
"close 12345 25.1"

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

@item forcemerge
@itemx merge
"forcemerge|merge 12345 54321"

The second bug number is read interactively.

@item invalid
"tags 12345 notabug" @*
"tags 12345 wontfix" @*
"close 12345"

@item noowner
"noowner 12345"

@item owner
"owner 12345 !"

@item reassign
"reassign 12345 @var{package}"

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

@item reopen
"reopen 12345"

@item retitle
"retitle 12345 @var{title}"

The new bug title is read interactively.

@item serious
@itemx important
@itemx normal
@itemx minor
@itemx wishlist
"severity 12345 serious|important|normal|minor|wishlist"

@item unarchive
"unarchive 12345"

@item unmerge
"unmerge 12345"

@item usertag
"user @var{username}" @*
"usertag 12345 @var{tag}"

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


@node Minor Mode
@chapter Minor Mode

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

@findex debbugs-browse-mode
@vindex debbugs-browse-function
This package adds a new minor mode @code{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 @code{debbugs-browse-function} controls, whether
@code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.

This minor mode is applicable for all URLs, not only bug references.
Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
shown in a bug report buffer, when @code{debbugs-browse-mode} is
enabled.


@node Command Index
@unnumbered Command Index
@printindex fn


@node Variable Index
@unnumbered Variable Index
@printindex vr


@node Key Index
@unnumbered Key Index
@printindex ky

@bye

@c Local Variables:
@c bug-reference-url-format: "http://debbugs.gnu.org/%s"
@c eval: (bug-reference-mode)
@c eval: (debbugs-browse-mode)
@c End: