2 @setfilename debbugs-ug.info
3 @settitle Debbugs User Guide
7 * Debbugs UG: (debbugs-ug). Debbugs User Interface in Emacs.
11 Copyright @copyright{} 2015-2016 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
42 @top Debbugs User Guide
44 Debbugs is a bugtracking system (BTS) that was initially written for
45 the Debian project but currently used also by the GNU project. The
46 main distinctive feature of Debbugs is that it's mostly email-based.
47 All actions on bug reports: opening, closing, changing the status,
48 commenting, forwarding are performed via email by sending specially
49 composed letters to the particular mail addresses. However, searching
50 the bug reports, querying bug report status and viewing comments have
51 been web-based for a long time. To overcome this inconvenience the
52 Debbugs/SOAP service was introduced.
54 Based on the Debbugs/SOAP service, frontends are written which offer
55 handling of bugs inside Emacs. These frontends are restricted to the
56 GNU Debbugs server. Bugs are presented either as tabulated list
57 (@code{debbugs-gnu}) or as @code{org-mode} TODO list
58 (@code{debbugs-org}, @pxref{Top, , Org Mode, org}). As backend they
59 use the @code{debbugs} Emacs library (@pxref{Top, , Debbugs
60 Programmer's Manual, debbugs}).
63 * Retrieving Bugs:: How to retrieve bugs.
64 * Searching Bugs:: How to search in the debbugs database.
65 * Layout:: How the results are presented.
66 * Minor Mode:: How to use browse bug URLs.
68 * Command Index:: Debbugs commands.
69 * Variable Index:: User options and variables.
70 * Key Index:: Keyboard strokes on bug report buffers.
75 @chapter Retrieving Bugs
77 Bugs are retrieved by the @code{debbugs-gnu} or @code{debbugs-org}
78 commands. In their simple version, they retrieve just bugs for the
79 @code{"emacs"} package on the GNU Debbugs server, filtered by bug
80 severities. Further filtering is possible when the commands are
83 When the bug numbers to be retrieved are known, the commands
84 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} are applicable.
87 @deffn {Command} debbugs-gnu severities &optional packages archivedp suppress tags
88 @deffnx {Command} debbugs-org severities &optional packages archivedp suppress tags
90 These commands retrieve bug reports from the GNU Debbugs server.
91 @code{debbugs-gnu} returns a tabulated list, and @code{debbugs-org}
92 returns a list of TODO items in @code{org-mode}. If there were more
93 than @code{debbugs-gnu-default-hits-per-page} bug results from the
94 query, there are widgets (@code{debbugs-gnu}) or links
95 (@code{debbugs-org}) in the result buffer for retrieving the other
98 @vindex debbugs-gnu-all-severities
99 @var{severities} is a list of strings which filter for the severities
100 of the bugs to be retrieved. Valid severities are @code{"serious"},
101 @code{"important"}, @code{"normal"}, @code{"minor"} and
102 @code{"wishlist"} (see also the constant
103 @code{debbugs-gnu-all-severities}). If the list is empty, there is no
104 filtering with respect to severities. The keyword @code{"tagged"},
105 which is also possible, is not a severity in the GNU Debbugs server
106 but allows to restrict the result to bugs with a given user tag.
108 @vindex debbugs-gnu-all-packages
109 @var{packages}, also a list of strings, point to the defined software
110 packages on the GNU Debbugs server which shall be taken into account.
111 The existing package names are compiled into the constant
112 @code{debbugs-gnu-all-packages}.
114 @var{archivedp}, if non-@code{nil}, extends the result also on
115 archived bugs on the GNU Debbugs server.
117 @var{suppress} shall also distinct between @code{nil} and
118 non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from
121 When @var{severities} contains the severity @code{"tagged"},
122 @var{tags} is consulted in order to restrict the result on bugs which
123 are tagged with one of the strings of the list @var{tags}. This list
124 can also be empty; in this case locally tagged bugs are included into
127 Called interactively, the commands require just the @var{severities}
128 and the @var{tags} (if @var{severities} includes @code{"tagged"}). In
129 order to provide the other arguments interactively, the commands must
130 be called with a prefix, like @kbd{C-u M-x debbugs-gnu}. In the
131 minibuffer, lists must be entered comma-separated.
133 @vindex debbugs-gnu-default-severities
134 @vindex debbugs-gnu-default-packages
135 Default values for interactive use could be configured in the customer
136 options @code{debbugs-gnu-default-severities} and
137 @code{debbugs-gnu-default-packages}.
139 @vindex debbugs-gnu-default-hits-per-page
140 When the result would exceed more than 500 bugs, the user is asked how
141 many bugs to retrieve at once. This value can be configured in the
142 customer option @code{debbugs-gnu-default-hits-per-page}. However, it
143 is not recommended to exceeds the default value.
145 @ref{Layout} for the presentation of the results.
150 @deffn {Command} debbugs-gnu-bugs &rest bugs
151 @deffnx {Command} debbugs-org-bugs &rest bugs
153 The commands @code{debbugs-gnu-bugs} and @code{debbugs-org-bugs} show
154 bugs specified by their bug number. Interactively, the bug numbers
155 must be entered as comma-separated list.
157 @ref{Layout} for the presentation of the results.
163 @chapter Searching in the Debbugs Database.
165 The GNU Debbugs server allows full text search in the database. It
167 @uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond,
168 HyperEstraier based search engine}@footnote{This has been added to the
169 Debbugs/SOAP backend of the GNU Debbugs server only.}.
171 @deffn {Command} debbugs-gnu-search
172 @deffnx {Command} debbugs-org-search
174 These both commands are completely interactive. They ask for a
175 @code{"search phrase"} for the full text search. It is just a string
176 which contains the words to be searched for, combined by operators
177 like AND, ANDNOT and OR. If there is no operator between the words,
178 AND is used by default.
180 Wild card searches are also supported. It can be used for forward
181 match search and backward match search. For example, "[BW] euro"
182 matches words which begin with "euro". "[EW] shere" matches words
183 which end with "sphere". Moreover, regular expressions are also
184 supported. For example, "[RX] ^inter.*al$" matches words which begin
185 with "inter" and end with "al".@footnote{Simplified forms, as
186 described in the Hyperestraier User Guide, are not supported.}
188 While the words to be searched for are case insensitive, the operators
189 must be specified case sensitive.
191 While the search for the phrase is performed only in the bodies of the
192 messages belonging to a bug report, it is also possible to
193 discriminate the search to further bug attributes. The commands ask
194 for such key-value pairs, until an empty key is returned. Possible
199 A comma-separated list of bug severities, @xref{Retrieving Bugs}.
202 A comma-separated list of defined software packages on the GNU Debbugs
203 server, @xref{Retrieving Bugs}.
206 A comma-separated list of defined user tags.
209 The address of the bug submitter.
212 A time period the bug has been in which the bug has been submitted or
216 Word(s) the subject of the bug report contains.
219 The status of the bug report. Valid values are "done", "forwarded"
223 It is also possible to apply these commands with an empty search
224 phrase. In this case, the GNU Debbugs server is searched only for
225 bugs which fulfill the given attributes. The attributes to be applied
226 are the same as already described, plus
230 Whether archived bugs shall be searched (no value to be entered).
233 Bugs which belong to a given source, if that attribute has set.
236 An arbitrary string the bug is annotated with. Usually, this is the
237 same as the status mentioned above.
242 The email address of the bug's owner, maintainer, or correspondent
243 (somebody who has participated in bug messages).
249 The date of the last update, or the date of the bug report / bug fix.
252 The date the bug has been unarchived, if ever.
255 The email address of the worker who has closed the bug (if done).
258 A URL or an email address.
261 The message id of the initial bug report.
264 The summary of the bug report.
267 Not all of these attributes could be queried on the GNU Debbugs server
268 via the Debbugs/SOAP backend. In this case, the results of a query
269 are discriminated on the client side, which is indicated by the string
270 "(client-side filter)" in the minibuffer after the attribute name.
277 The commands described in the previous chapters generate (a) report
278 buffer(s) applicable for navigation. @code{debbugs-gnu-*} return a
279 tabulated list, and @code{debbugs-org-*} return a list of TODO items
283 * Tabulated Lists:: Tabulated Lists.
284 * TODO Items:: TODO Items.
285 * Control Messages:: Control Messages.
289 @node Tabulated Lists
290 @section Tabulated Lists
292 A tabulated list of bug reports consist of four columns for every bug
293 entry: @code{Id} (the bug number), @code{State} (some bug attributes),
294 @code{Submitter} (the name of the bug submitter), and @code{Title}
295 (the bug subject). Per default the bugs are sorted by @code{Id}; this
296 could be changed by clicking in the headline.
298 Per bug retrieval only up to 500
299 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
300 presented in a buffer. If there shall be presented more bugs, widgets
301 are placed on the top and bottom of the buffer for navigation to
302 further report buffers.
304 Different foreground colours present further information on the bug
305 report. If the bug number uses a red colour
306 (@code{debbugs-gnu-tagged}), the bug has been tagged locally. The
307 same face is used to mark bugs in the submitter or title column, when
308 the bug has been reported / is maintained by the user.
310 The bug state could appear in different colours: red
311 (@code{debbugs-gnu-new}, nobody has answered yet to this bug),
312 ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
313 recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
314 pending), orange (@code{debbugs-gnu-stale}, the bug has not been
315 touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
316 is closed). Archived bugs are shown with inverse face
317 (@code{debbugs-gnu-archived}).
319 The bug report buffers have enabled the minor
320 @code{debbugs-gnu-mode}. This enables the following key strokes:
322 @multitable @columnfractions .20 .80
325 @kindex @kbd{@key{RET}}
327 @kindex @kbd{@key{mouse-1}}
328 @kbd{@key{mouse-1}} @*
329 @kindex @kbd{@key{mouse-2}}
330 @kbd{@key{mouse-2}} @tab
331 @code{debbugs-gnu-select-report} @*
332 Show the email messages that discuss the bug.
337 @code{debbugs-gnu-display-status} @*
338 Show all bug attributes.
343 @code{debbugs-gnu-narrow-to-status} @*
344 Narrow the list of bugs to the bugs that match the given regex in
345 @code{State}, @code{Submitter} or @code{Title}.
350 @code{debbugs-gnu-show-all-blocking-reports} @*
351 Narrow the list of bug reports to the ones that are blocking the
357 @code{debbugs-gnu-widen} @*
358 Restore the full list again after narrowing.
363 @code{debbugs-gnu-rescan} @*
364 Reload all bugs from the GNU Debbugs server.
371 @code{debbugs-gnu-show-blocking-reports} @*
372 @code{debbugs-gnu-show-blocked-by-reports} @*
373 Show all bug reports which are blocking / blocked by this bug.
378 @code{debbugs-gnu-toggle-sort} @*
379 Toggle sorting order of bugs.
384 @code{debbugs-gnu-toggle-tag} @*
385 Toggle local tag of bugs.
390 @code{debbugs-gnu-toggle-suppress} @*
391 Toggle showing of closed bugs.
396 @code{debbugs-gnu-send-control-message} @*
397 Send a control message for this bug, @ref{Control Messages}.
401 @vindex debbugs-gnu-mail-backend
402 The user option @code{debbugs-gnu-mail-backend} controls the
403 presentation of email messages produced by typing @kbd{@key{RET}} or
404 by clicking the mouse on a bug: if its value is @code{gnus}, the
405 default, a GNUS ephemeral group for that bug will be shown; if its
406 value is @code{rmail}, the command will present an Rmail folder
413 TODO items are offered as usual in @code{org-mode}. The bug
414 attributes are mapped onto properties of these items. They can be
415 shown by the usual navigation in @code{org-mode}.
417 Per bug retrieval only up to 500
418 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
419 presented in a buffer. At the end of the buffer there is a link,
420 which allows to append the next 500 bugs to the list.
422 Bug severities are mapped onto org severities, see
423 @code{debbugs-org-severity-priority}.
425 The bug report buffers have enabled the minor
426 @code{debbugs-gnu-mode}. This enables the following key strokes:
428 @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}
431 @kindex @kbd{@key{TAB}}
434 Outline the bug report attributes in @code{org-mode}.
437 @kindex @kbd{C-c # d}
439 @code{debbugs-gnu-display-status} @*
440 Show all bug attributes.
443 @kindex @kbd{C-c # t}
445 @code{debbugs-gnu-toggle-tag} @*
446 Toggle local tag of bugs.
449 @kindex @kbd{C-c # C}
451 @code{debbugs-gnu-send-control-message} @*
452 Send a control message for this bug, @ref{Control Messages}.
456 When the bug attributes are shown by @code{org-cycle}, there is a link
457 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
460 @node Control Messages
461 @section Control Messages
463 Debbugs control messages are sent by email to the GNU Debbugs control
464 server. Their format is described in
465 @uref{http://debbugs.gnu.org/server-control.html}.
467 A control message can be initiated in the tabulated list of bugs, in
468 the list of org TODO items, or in the GNUS ephemeral group or Rmail
469 folder opened for the messages belonging to a given bug. Control
470 messages can be sent to unarchived bugs only, in case a bug is
471 archived the control message @samp{unarchive} must be sent first.
473 In the minibuffer, the following control messages can be requested
474 (assuming that 12345 is the bug the control message is intended for).
475 The strings show the exact format of the control messages.
480 "block|unblock 12345 by 54321"
482 The second bug number is read interactively. It could be also a list
483 of comma-separated bug numbers.
488 The second argument, the Emacs version, is read interactively.
498 @itemx unreproducible
500 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
502 "tags 12345 patch|pending|security|unreproducible|wontfix"
506 @itemx doneunreproducible
508 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
511 The second argument in the close message, the Emacs version, is read
516 "forcemerge|merge 12345 54321"
518 The second bug number is read interactively.
525 "severity 12345 important|minor|normal|serious|wishlist"
528 "tags 12345 notabug" @*
529 "tags 12345 wontfix" @*
539 "reassign 12345 @var{package}"
541 The package name on the GNU Debbugs server is read interactively.
553 "user @var{username}" @*
554 "usertag 12345 @var{tag}"
556 The username, read interactively, is either a package name or an email
557 address. The tag to be set is also read interactively.
564 Emacs uses @file{bug-reference.el} for adding hyperlinks to bugs in
565 files like @file{ChangeLog}, or in commentary sections of other files.
566 The reference to such bugs have a specialized format,
567 @uref{Bug#12345}. The hyperlinks are implemented as minor modes
568 @code{bug-reference-mode} and @code{bug-reference-prog-mode}.
570 @findex debbugs-browse-mode
571 @vindex debbugs-browse-function
572 This package adds a new minor mode @code{debbugs-browse-mode} on top
573 of them. Instead of using the default built-in Emacs browser for a
574 given bug reference, it opens a corresponding bug report buffer. The
575 customer option @code{debbugs-browse-function} controls, whether
576 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.
578 This minor mode is applicable for all URLs, not only bug references.
579 Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
580 shown in a bug report buffer, when @code{debbugs-browse-mode} is
585 @unnumbered Command Index
590 @unnumbered Variable Index
595 @unnumbered Key Index
601 @c bug-reference-url-format: "http://debbugs.gnu.org/%s"
602 @c eval: (bug-reference-mode)
603 @c eval: (debbugs-browse-mode)