-This is debbugs-ug.info, produced by makeinfo version 5.0 from
+This is debbugs-ug.info, produced by makeinfo version 6.0 from
debbugs-ug.texi.
-Copyright (C) 2015 Free Software Foundation, Inc.
+Copyright (C) 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.
+ 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.
+ 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,
+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
+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', *note
+Org Mode: (org)Top.). As backend they use the 'debbugs' Emacs library
(*note Debbugs Programmer's Manual: (debbugs)Top.).
* Menu:
*****************
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.
+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.
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.
+ '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 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'.
+ 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.
+ non-'nil', closed bugs are suppressed from being retrieved from
+ the Debbugs server. Which bugs are regarded as suppressed is
+ configured in the customer option 'debbugs-gnu-suppress-bugs'.
+ Per 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 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.
+ specified by their bug number. Interactively, the bug numbers
+ must be entered as comma-separated list.
*note Layout:: for the presentation of the results.
2 Searching in the Debbugs Database.
************************************
-The GNU Debbugs server allows full text search in the database. It uses
-a HyperEstraier based search engine
+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
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.
+ 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)
+ 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
+ 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
Bugs::.
'package'
- A comma-separated list of defined software packages on the GNU
- Debbugs server, *Note Retrieving Bugs::.
+ 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.
+ The email address of the bug submitter.
'date'
A time period the bug has been in which the bug has been
"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
+ 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
set.
'tag'
- An arbitrary string the bug is annotated with. Usually, this
- is the same as the status mentioned above.
+ 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).
+ correspondent (somebody who has participated in bug
+ messages).
'log_modified'
'last_modified'
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.
+ 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 ----------
********
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'.
+buffer(s) applicable for navigation. 'debbugs-gnu-*' return a
+tabulated list, and 'debbugs-org-*' return a list of TODO items in
+'org-mode'.
* Menu:
===================
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.
+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 descending by '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 ('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
+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-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).
+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>' 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::.
-
+'<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. With a prefix argument 'C-u', the
+ bug status cache is disabled, and all bug reports are
+ retrieved 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
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'.
+ The bug report buffers have enabled the minor 'debbugs-org-mode'.
This enables the following key strokes:
'<TAB>' 'org-cycle'
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.
+ 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'
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"
'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"
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.
+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.
+ 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
\0\b[index\0\b]
* Menu:
-* debbugs-browse-mode: Minor Mode. (line 12)
-* debbugs-gnu: Retrieving Bugs. (line 14)
-* debbugs-gnu-bugs: Retrieving Bugs. (line 68)
-* debbugs-gnu-search: Searching Bugs. (line 10)
-* debbugs-org: Retrieving Bugs. (line 16)
-* debbugs-org-bugs: Retrieving Bugs. (line 69)
-* debbugs-org-search: Searching Bugs. (line 11)
+* debbugs-browse-mode: Minor Mode. (line 12)
+* debbugs-gnu: Retrieving Bugs. (line 15)
+* debbugs-gnu-bugs: Retrieving Bugs. (line 69)
+* debbugs-gnu-search: Searching Bugs. (line 10)
+* debbugs-org: Retrieving Bugs. (line 17)
+* debbugs-org-bugs: Retrieving Bugs. (line 70)
+* debbugs-org-search: Searching Bugs. (line 11)
\1f
File: debbugs-ug.info, Node: Variable Index, Next: Key Index, Prev: Command Index, Up: Top
\0\b[index\0\b]
* Menu:
-* debbugs-browse-function: Minor Mode. (line 12)
-* debbugs-gnu-all-packages: Retrieving Bugs. (line 35)
-* debbugs-gnu-all-severities: Retrieving Bugs. (line 26)
-* debbugs-gnu-default-hits-per-page: Retrieving Bugs. (line 61)
-* debbugs-gnu-default-packages: Retrieving Bugs. (line 57)
-* debbugs-gnu-default-severities: Retrieving Bugs. (line 57)
+* debbugs-browse-function: Minor Mode. (line 12)
+* debbugs-gnu-all-packages: Retrieving Bugs. (line 36)
+* debbugs-gnu-all-severities: Retrieving Bugs. (line 27)
+* debbugs-gnu-default-packages: Retrieving Bugs. (line 63)
+* debbugs-gnu-default-severities: Retrieving Bugs. (line 63)
+* debbugs-gnu-default-suppress-bugs: Retrieving Bugs. (line 44)
+* debbugs-gnu-mail-backend: Tabulated Lists. (line 71)
\1f
File: debbugs-ug.info, Node: Key Index, Prev: Variable Index, Up: Top
\0\b[index\0\b]
* Menu:
-* 'B': Tabulated Lists. (line 44)
-* 'b': Tabulated Lists. (line 45)
-* 'C': Tabulated Lists. (line 57)
-* 'C-c # C': TODO Items. (line 30)
-* 'C-c # d': TODO Items. (line 24)
-* 'C-c # t': TODO Items. (line 27)
-* 'd': Tabulated Lists. (line 38)
-* 'g': Tabulated Lists. (line 41)
-* '<mouse-1>': Tabulated Lists. (line 34)
-* '<mouse-2>': Tabulated Lists. (line 36)
-* '<RET>': Tabulated Lists. (line 34)
-* 's': Tabulated Lists. (line 48)
-* 't': Tabulated Lists. (line 51)
-* '<TAB>': TODO Items. (line 21)
-* 'x': Tabulated Lists. (line 54)
+* '/': Tabulated Lists. (line 36)
+* 'B': Tabulated Lists. (line 52)
+* 'b': Tabulated Lists. (line 53)
+* 'C': Tabulated Lists. (line 66)
+* 'C-c # C': TODO Items. (line 25)
+* 'C-c # d': TODO Items. (line 19)
+* 'C-c # t': TODO Items. (line 22)
+* 'd': Tabulated Lists. (line 33)
+* 'g': Tabulated Lists. (line 47)
+* '<mouse-1>': Tabulated Lists. (line 30)
+* '<mouse-2>': Tabulated Lists. (line 31)
+* 'R': Tabulated Lists. (line 40)
+* '<RET>': Tabulated Lists. (line 29)
+* 's': Tabulated Lists. (line 57)
+* 't': Tabulated Lists. (line 60)
+* '<TAB>': TODO Items. (line 16)
+* 'w': Tabulated Lists. (line 44)
+* 'x': Tabulated Lists. (line 63)
\1f
Tag Table:
-Node: Top\7f1087
-Node: Retrieving Bugs\7f2625
-Node: Searching Bugs\7f6147
-Ref: Searching Bugs-Footnote-1\7f10016
-Ref: Searching Bugs-Footnote-2\7f10104
-Node: Layout\7f10195
-Node: Tabulated Lists\7f10670
-Node: TODO Items\7f13104
-Node: Control Messages\7f14369
-Node: Minor Mode\7f16529
-Node: Command Index\7f17467
-Node: Variable Index\7f18128
-Node: Key Index\7f18717
+Node: Top\7f1097
+Node: Retrieving Bugs\7f2635
+Node: Searching Bugs\7f6095
+Ref: Searching Bugs-Footnote-1\7f9980
+Ref: Searching Bugs-Footnote-2\7f10068
+Node: Layout\7f10159
+Node: Tabulated Lists\7f10634
+Node: TODO Items\7f13881
+Node: Control Messages\7f14928
+Node: Minor Mode\7f17324
+Node: Command Index\7f18263
+Node: Variable Index\7f18910
+Node: Key Index\7f19558
\1f
End Tag Table