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
313 is closed). Archived bugs are shown with inverse face
314 (@code{debbugs-gnu-archived}).
316 The bug report buffers have enabled the minor
317 @code{debbugs-gnu-mode}. This enables the following key strokes:
319 @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}
322 @kindex @kbd{@key{RET}}
324 @kindex @kbd{@key{mouse-1}}
326 @kindex @kbd{@key{mouse-2}}
327 @kbd{@key{mouse-2}} @tab
328 @code{debbugs-gnu-select-report} @*
329 Show the email messages that discuss the bug.
334 @code{debbugs-gnu-display-status} @*
335 Show all bug attributes.
340 @code{debbugs-gnu-narrow-to-status}
341 Narrow the list of bugs to the bugs that match the given regex.
346 @code{debbugs-gnu-widen}
347 Restore the full list again after narrowing.
352 @code{debbugs-gnu-show-all-blocking-reports}
353 Narrow the list of reports to the ones that are blocking the current
359 @code{debbugs-gnu-rescan} @*
360 Reload all bugs from the GNU Debbugs server.
365 @code{debbugs-gnu-show-blocking-reports}
369 @code{debbugs-gnu-show-blocked-by-reports} @*
370 Show all bug reports which are blocking / blocked by this bug.
375 @code{debbugs-gnu-toggle-sort} @*
376 Toggle sorting order of bugs.
381 @code{debbugs-gnu-toggle-tag} @*
382 Toggle local tag of bugs.
387 @code{debbugs-gnu-toggle-suppress} @*
388 Toggle showing of closed bugs.
393 @code{debbugs-gnu-send-control-message} @*
394 Send a control message for this bug, @ref{Control Messages}.
398 @vindex debbugs-gnu-mail-backend
399 The user option @code{debbugs-gnu-mail-backend} controls the
400 presentation of email messages produced by typing @kbd{@key{RET}} or
401 by clicking the mouse on a bug: if its value is @code{gnus}, the
402 default, a GNUS ephemeral group for that bug will be shown; if its
403 value is @code{rmail}, the command will present an Rmail folder
409 TODO items are offered as usual in @code{org-mode}. The bug
410 attributes are mapped onto properties of these items. They can be
411 shown by the usual navigation in @code{org-mode}.
413 Per bug retrieval only up to 500
414 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
415 presented in a buffer. At the end of the buffer there is a link,
416 which allows to append the next 500 bugs to the list.
418 Bug severities are mapped onto org severities, see
419 @code{debbugs-org-severity-priority}.
421 The bug report buffers have enabled the minor
422 @code{debbugs-gnu-mode}. This enables the following key strokes:
424 @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}
427 @kindex @kbd{@key{TAB}}
430 Outline the bug report attributes in @code{org-mode}.
433 @kindex @kbd{C-c # d}
435 @code{debbugs-gnu-display-status} @*
436 Show all bug attributes.
439 @kindex @kbd{C-c # t}
441 @code{debbugs-gnu-toggle-tag} @*
442 Toggle local tag of bugs.
445 @kindex @kbd{C-c # C}
447 @code{debbugs-gnu-send-control-message} @*
448 Send a control message for this bug, @ref{Control Messages}.
452 When the bug attributes are shown by @code{org-cycle}, there is a link
453 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
456 @node Control Messages
457 @section Control Messages
459 Debbugs control messages are sent by email to the GNU Debbugs control
460 server. Their format is described in
461 @uref{http://debbugs.gnu.org/server-control.html}.
463 A control message can be initiated in the tabulated list of bugs, in
464 the list of org TODO items, or in the GNUS ephemeral group or Rmail
465 folder opened for the messages belonging to a given bug. Control
466 messages can be sent to unarchived bugs only, in case a bug is
467 archived the control message @samp{unarchive} must be sent first.
469 In the minibuffer, the following control messages can be requested
470 (assuming that 12345 is the bug the control message is intended for).
471 The strings show the exact format of the control messages.
476 "block|unblock 12345 by 54321"
478 The second bug number is read interactively. It could be also a list
479 of comma-separated bug numbers.
484 The second argument, the Emacs version, is read interactively.
494 @itemx unreproducible
496 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
498 "tags 12345 patch|pending|security|unreproducible|wontfix"
502 @itemx doneunreproducible
504 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
507 The second argument in the close message, the Emacs version, is read
512 "forcemerge|merge 12345 54321"
514 The second bug number is read interactively.
521 "severity 12345 important|minor|normal|serious|wishlist"
524 "tags 12345 notabug" @*
525 "tags 12345 wontfix" @*
535 "reassign 12345 @var{package}"
537 The package name on the GNU Debbugs server is read interactively.
549 "user @var{username}" @*
550 "usertag 12345 @var{tag}"
552 The username, read interactively, is either a package name or an email
553 address. The tag to be set is also read interactively.
560 Emacs uses @file{bug-reference.el} for adding hyperlinks to bugs in
561 files like @file{ChangeLog}, or in commentary sections of other files.
562 The reference to such bugs have a specialized format,
563 @uref{Bug#12345}. The hyperlinks are implemented as minor modes
564 @code{bug-reference-mode} and @code{bug-reference-prog-mode}.
566 @findex debbugs-browse-mode
567 @vindex debbugs-browse-function
568 This package adds a new minor mode @code{debbugs-browse-mode} on top
569 of them. Instead of using the default built-in Emacs browser for a
570 given bug reference, it opens a corresponding bug report buffer. The
571 customer option @code{debbugs-browse-function} controls, whether
572 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.
574 This minor mode is applicable for all URLs, not only bug references.
575 Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
576 shown in a bug report buffer, when @code{debbugs-browse-mode} is
581 @unnumbered Command Index
586 @unnumbered Variable Index
591 @unnumbered Key Index
597 @c bug-reference-url-format: "http://debbugs.gnu.org/%s"
598 @c eval: (bug-reference-mode)
599 @c eval: (debbugs-browse-mode)