2 @setfilename debbugs-ug.info
3 @settitle Debbugs User Guide
7 * Debbugs UG: (debbugs-ug). Debbugs User Interface in Emacs.
11 Copyright @copyright{} 2015 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of
18 the license is included in the section entitled ``GNU Free Documentation
19 License'' in the Emacs manual.
21 This document is part of a collection distributed under the GNU Free
22 Documentation License. If you want to distribute this document
23 separately from the collection, you can do so by adding a copy of the
24 license to the document, as described in section 6 of the license.
26 All Emacs Lisp code contained in this document may be used, distributed,
27 and modified without restriction.
32 @title Debbugs User Guide
33 @author by Michael Albinus
41 @top Debbugs User Guide
43 Debbugs is a bugtracking system (BTS) that was initially written for
44 the Debian project but currently used also by the GNU project. The
45 main distinctive feature of Debbugs is that it's mostly email-based.
46 All actions on bug reports: opening, closing, changing the status,
47 commenting, forwarding are performed via email by sending specially
48 composed letters to the particular mail addresses. However, searching
49 the bug reports, querying bug report status and viewing comments have
50 been web-based for a long time. To overcome this inconvenience the
51 Debbugs/SOAP service was introduced.
53 Based on the Debbugs/SOAP service, frontends are written which offer
54 handling of bugs inside Emacs. These frontends are restricted to the
55 GNU Debbugs server. Bugs are presented either as tabulated list
56 (@code{debbugs-gnu}) or as @code{org-mode} TODO list
57 (@code{debbugs-org}, @pxref{Top, , Org Mode, org}). As backend they
58 use the @code{debbugs} Emacs library (@pxref{Top, , Debbugs
59 Programmer's Manual, debbugs}).
62 * Retrieving Bugs:: How to retrieve bugs.
63 * Searching Bugs:: How to search in the debbugs database.
64 * Layout:: How the results are presented.
65 * Minor Mode:: How to use browse bug URLs.
67 * Command Index:: Debbugs commands.
68 * Variable Index:: User options and variables.
69 * Key Index:: Keyboard strokes on bug report buffers.
73 @chapter Retrieving Bugs
75 Bugs are retrieved by the @code{debbugs-gnu} or @code{debbugs-org}
76 commands. In their simple version, they retrieve just bugs for the
77 @code{"emacs"} package on the GNU Debbugs server, filtered by bug
78 severities. Further filtering is possible when the commands are
81 When the bug numbers to be retrieved are known, the commands
82 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} are applicable.
85 @deffn {Command} debbugs-gnu severities &optional packages archivedp suppress tags
86 @deffnx {Command} debbugs-org severities &optional packages archivedp suppress tags
88 These commands retrieve bug reports from the GNU Debbugs server.
89 @code{debbugs-gnu} returns a tabulated list, and @code{debbugs-org}
90 returns a list of TODO items in @code{org-mode}. If there were more
91 than @code{debbugs-gnu-default-hits-per-page} bug results from the
92 query, there are widgets (@code{debbugs-gnu}) or links
93 (@code{debbugs-org}) in the result buffer for retrieving the other
96 @vindex debbugs-gnu-all-severities
97 @var{severities} is a list of strings which filter for the severities
98 of the bugs to be retrieved. Valid severities are @code{"serious"},
99 @code{"important"}, @code{"normal"}, @code{"minor"} and
100 @code{"wishlist"} (see also the constant
101 @code{debbugs-gnu-all-severities}). If the list is empty, there is no
102 filtering with respect to severities. The keyword @code{"tagged"},
103 which is also possible, is not a severity in the GNU Debbugs server
104 but allows to restrict the result to bugs with a given user tag.
106 @vindex debbugs-gnu-all-packages
107 @var{packages}, also a list of strings, point to the defined software
108 packages on the GNU Debbugs server which shall be taken into account.
109 The existing package names are compiled into the constant
110 @code{debbugs-gnu-all-packages}.
112 @var{archivedp}, if non-@code{nil}, extends the result also on
113 archived bugs on the GNU Debbugs server.
115 @var{suppress} shall also distinct between @code{nil} and
116 non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from
119 When @var{severities} contains the severity @code{"tagged"},
120 @var{tags} is consulted in order to restrict the result on bugs which
121 are tagged with one of the strings of the list @var{tags}. This list
122 can also be empty; in this case locally tagged bugs are included into
125 Called interactively, the commands require just the @var{severities}
126 and the @var{tags} (if @var{severities} includes @code{"tagged"}). In
127 order to provide the other arguments interactively, the commands must
128 be called with a prefix, like @kbd{C-u M-x debbugs-gnu}. In the
129 minibuffer, lists must be entered comma-separated.
131 @vindex debbugs-gnu-default-severities
132 @vindex debbugs-gnu-default-packages
133 Default values for interactive use could be configured in the customer
134 options @code{debbugs-gnu-default-severities} and
135 @code{debbugs-gnu-default-packages}.
137 @vindex debbugs-gnu-default-hits-per-page
138 When the result would exceed more than 500 bugs, the user is asked how
139 many bugs to retrieve at once. This value can be configured in the
140 customer option @code{debbugs-gnu-default-hits-per-page}. However, it
141 is not recommended to exceeds the default value.
143 @ref{Layout} for the presentation of the results.
148 @deffn {Command} debbugs-gnu-bugs &rest bugs
149 @deffnx {Command} debbugs-org-bugs &rest bugs
151 The commands @code{debbugs-gnu-bugs} and @code{debbugs-org-bugs} show
152 bugs specified by their bug number. Interactively, the bug numbers
153 must be entered as comma-separated list.
155 @ref{Layout} for the presentation of the results.
161 @chapter Searching in the Debbugs Database.
163 The GNU Debbugs server allows full text search in the database. It
165 @uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond,
166 HyperEstraier based search engine}@footnote{This has been added to the
167 Debbugs/SOAP backend of the GNU Debbugs server only.}.
169 @deffn {Command} debbugs-gnu-search
170 @deffnx {Command} debbugs-org-search
172 These both commands are completely interactive. They ask for a
173 @code{"search phrase"} for the full text search. It is just a string
174 which contains the words to be searched for, combined by operators
175 like AND, ANDNOT and OR. If there is no operator between the words,
176 AND is used by default.
178 Wild card searches are also supported. It can be used for forward
179 match search and backward match search. For example, "[BW] euro"
180 matches words which begin with "euro". "[EW] shere" matches words
181 which end with "sphere". Moreover, regular expressions are also
182 supported. For example, "[RX] ^inter.*al$" matches words which begin
183 with "inter" and end with "al".@footnote{Simplified forms, as
184 described in the Hyperestraier User Guide, are not supported.}
186 While the words to be searched for are case insensitive, the operators
187 must be specified case sensitive.
189 While the search for the phrase is performed only in the bodies of the
190 messages belonging to a bug report, it is also possible to
191 discriminate the search to further bug attributes. The commands ask
192 for such key-value pairs, until an empty key is returned. Possible
197 A comma-separated list of bug severities, @xref{Retrieving Bugs}.
200 A comma-separated list of defined software packages on the GNU Debbugs
201 server, @xref{Retrieving Bugs}.
204 A comma-separated list of defined user tags.
207 The address of the bug submitter.
210 A time period the bug has been in which the bug has been submitted or
214 Word(s) the subject of the bug report contains.
217 The status of the bug report. Valid values are "done", "forwarded"
221 It is also possible to apply these commands with an empty search
222 phrase. In this case, the GNU Debbugs server is searched only for
223 bugs which fulfill the given attributes. The attributes to be applied
224 are the same as already described, plus
228 Whether archived bugs shall be searched (no value to be entered).
231 Bugs which belong to a given source, if that attribute has set.
234 An arbitrary string the bug is annotated with. Usually, this is the
235 same as the status mentioned above.
240 The email address of the bug's owner, maintainer, or correspondent
241 (somebody who has participated in bug messages).
247 The date of the last update, or the date of the bug report / bug fix.
250 The date the bug has been unarchived, if ever.
253 The email address of the worker who has closed the bug (if done).
256 A URL or an email address.
259 The message id of the initial bug report.
262 The summary of the bug report.
265 Not all of these attributes could be queried on the GNU Debbugs server
266 via the Debbugs/SOAP backend. In this case, the results of a query
267 are discriminated on the client side, which is indicated by the string
268 "(client-side filter)" in the minibuffer after the attribute name.
275 The commands described in the previous chapters generate (a) report
276 buffer(s) applicable for navigation. @code{debbugs-gnu-*} return a
277 tabulated list, and @code{debbugs-org-*} return a list of TODO items
281 * Tabulated Lists:: Tabulated Lists.
282 * TODO Items:: TODO Items.
283 * Control Messages:: Control Messages.
286 @node Tabulated Lists
287 @section Tabulated Lists
289 A tabulated list of bug reports consist of four columns for every bug
290 entry: @code{Id} (the bug number), @code{State} (some bug attributes),
291 @code{Submitter} (the name of the bug submitter), and @code{Title}
292 (the bug subject). Per default the bugs are sorted by @code{Id}; this
293 could be changed by clicking in the headline.
295 Per bug retrieval only up to 500
296 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
297 presented in a buffer. If there shall be presented more bugs, widgets
298 are placed on the top and bottom of the buffer for navigation to
299 further report buffers.
301 Different foreground colours present further information on the bug
302 report. If the bug number uses a red colour
303 (@code{debbugs-gnu-tagged}), the bug has been tagged locally. The
304 same face is used to mark bugs in the submitter or title column, when
305 the bug has been reported / is maintained by the user.
307 The bug state could appear in different colours: red
308 (@code{debbugs-gnu-new}, nobody has answered yet to this bug),
309 ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
310 recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
311 pending), orange (@code{debbugs-gnu-stale}, the bug has not been
312 touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
315 The bug report buffers have enabled the minor
316 @code{debbugs-gnu-mode}. This enables the following key strokes:
318 @multitable {@kbd{@key{mouse-2}}} {Some very very very long long text Some very very very long long text Some very very very long long text}
321 @kindex @kbd{@key{RET}}
323 @kindex @kbd{@key{mouse-1}}
325 @kindex @kbd{@key{mouse-2}}
326 @kbd{@key{mouse-2}} @tab
327 @code{debbugs-gnu-select-report} @*
328 Open a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
333 @code{debbugs-gnu-display-status} @*
334 Show all bug attributes.
339 @c @code{debbugs-gnu-narrow-to-status}
344 @c @code{debbugs-gnu-widen}
349 @code{debbugs-gnu-rescan} @*
350 Reload all bugs from the GNU Debbugs server.
355 @code{debbugs-gnu-show-blocking-reports}
359 @code{debbugs-gnu-show-blocked-by-reports} @*
360 Show all bug reports which are blocking / blocked by this bug.
365 @code{debbugs-gnu-toggle-sort} @*
366 Toggle sorting order of bugs.
371 @code{debbugs-gnu-toggle-tag} @*
372 Toggle local tag of bugs.
377 @code{debbugs-gnu-toggle-suppress} @*
378 Toggle showing of closed bugs.
383 @code{debbugs-gnu-send-control-message} @*
384 Send a control message for this bug, @ref{Control Messages}.
392 TODO items are offered as usual in @code{org-mode}. The bug
393 attributes are mapped onto properties of these items. They can be
394 shown by the usual navigation in @code{org-mode}.
396 Per bug retrieval only up to 500
397 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
398 presented in a buffer. At the end of the buffer there is a link,
399 which allows to append the next 500 bugs to the list.
401 Bug severities are mapped onto org severities, see
402 @code{debbugs-org-severity-priority}.
404 The bug report buffers have enabled the minor
405 @code{debbugs-gnu-mode}. This enables the following key strokes:
407 @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}
410 @kindex @kbd{@key{TAB}}
413 Outline the bug report attributes in @code{org-mode}.
416 @kindex @kbd{C-c # d}
418 @code{debbugs-gnu-display-status} @*
419 Show all bug attributes.
422 @kindex @kbd{C-c # t}
424 @code{debbugs-gnu-toggle-tag} @*
425 Toggle local tag of bugs.
428 @kindex @kbd{C-c # C}
430 @code{debbugs-gnu-send-control-message} @*
431 Send a control message for this bug, @ref{Control Messages}.
435 When the bug attributes are shown by @code{org-cycle}, there is a link
436 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
439 @node Control Messages
440 @section Control Messages
442 Debbugs control messages are sent by email to the GNU Debbugs control
443 server. Their format is described in
444 @uref{http://debbugs.gnu.org/server-control.html}.
446 A control message can be initiated in the tabulated list of bugs, in
447 the list of org TODO items, or in the GNUS ephemeral group opened for
448 the messages belonging to a given bug. In the minibuffer, the
449 following control messages can be requested (assuming that 12345 is
450 the bug the control message is intended for). The strings show the
451 exact format of the control messages.
456 "block|unblock 12345 by 54321"
458 The second bug number is read interactively. It could be also a list
459 of comma-separated bug numbers.
464 The second argument, the Emacs version, is read interactively.
474 @itemx unreproducible
476 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
478 "tags 12345 patch|pending|security|unreproducible|wontfix"
482 @itemx doneunreproducible
484 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
487 The second argument in the close message, the Emacs version, is read
492 "forcemerge|merge 12345 54321"
494 The second bug number is read interactively.
501 "severity 12345 important|minor|normal|serious|wishlist"
504 "tags 12345 notabug" @*
505 "tags 12345 wontfix" @*
515 "reassign 12345 @var{package}"
517 The package name on the GNU Debbugs server is read interactively.
529 "user @var{username}" @*
530 "usertag 12345 @var{tag}"
532 The username, read interactively, is either a package name or an email
533 address. The tag to be set is also read interactively.
540 Emacs uses @file{bug-reference.el} for adding hyperlinks to bugs in
541 files like @file{ChangeLog}, or in commentary sections of other files.
542 The reference to such bugs have a specialized format,
543 @uref{Bug#12345}. The hyperlinks are implemented as minor modes
544 @code{bug-reference-mode} and @code{bug-reference-prog-mode}.
546 @findex debbugs-browse-mode
547 @vindex debbugs-browse-function
548 This package adds a new minor mode @code{debbugs-browse-mode} on top
549 of them. Instead of using the default built-in Emacs browser for a
550 given bug reference, it opens a corresponding bug report buffer. The
551 customer option @code{debbugs-browse-function} controls, whether
552 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.
554 This minor mode is applicable for all URLs, not only bug references.
555 Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
556 shown in a bug report buffer, when @code{debbugs-browse-mode} is
561 @unnumbered Command Index
566 @unnumbered Variable Index
571 @unnumbered Key Index
577 @c bug-reference-url-format: "http://debbugs.gnu.org/%s"
578 @c eval: (bug-reference-mode)
579 @c eval: (debbugs-browse-mode)