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 email addresses. However,
50 searching the bug reports, querying bug report status and viewing
51 comments have been web-based for a long time. To overcome this
52 inconvenience the 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}. In order not to
93 stress the GNU Debbugs server, the bugs are retrieved in chunks of 500
94 bugs. However, the bug report buffer shows all retrieved bugs then,
95 in reverse bug number order.
97 @vindex debbugs-gnu-all-severities
98 @var{severities} is a list of strings which filter for the severities
99 of the bugs to be retrieved. Valid severities are @code{"serious"},
100 @code{"important"}, @code{"normal"}, @code{"minor"} and
101 @code{"wishlist"} (see also the constant
102 @code{debbugs-gnu-all-severities}). If the list is empty, there is no
103 filtering with respect to severities. The keyword @code{"tagged"},
104 which is also possible, is not a severity in the GNU Debbugs server
105 but allows to restrict the result to bugs with a given user tag.
107 @vindex debbugs-gnu-all-packages
108 @var{packages}, also a list of strings, point to the defined software
109 packages on the GNU Debbugs server which shall be taken into account.
110 The existing package names are compiled into the constant
111 @code{debbugs-gnu-all-packages}.
113 @var{archivedp}, if non-@code{nil}, extends the result also on
114 archived bugs on the GNU Debbugs server.
116 @vindex debbugs-gnu-default-suppress-bugs
117 @var{suppress} shall also distinct between @code{nil} and
118 non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from
119 being retrieved from the Debbugs server. Which bugs are regarded as
120 suppressed is configured in the customer option
121 @code{debbugs-gnu-suppress-bugs}. Per default, bugs marked as
122 @code{"done"} are suppressed from being retrieved.
124 When @var{severities} contains the severity @code{"tagged"},
125 @var{tags} is consulted in order to restrict the result on bugs which
126 are tagged with one of the strings of the list @var{tags}. This list
127 can also be empty; in this case locally tagged bugs are included into
130 Called interactively, the commands require just the @var{severities}
131 and the @var{tags} (if @var{severities} includes @code{"tagged"}). In
132 order to provide the other arguments interactively, the commands must
133 be called with a prefix, like @kbd{C-u M-x debbugs-gnu}. In the
134 minibuffer, lists must be entered comma-separated.
136 @vindex debbugs-gnu-default-severities
137 @vindex debbugs-gnu-default-packages
138 Default values for interactive use could be configured in the customer
139 options @code{debbugs-gnu-default-severities} and
140 @code{debbugs-gnu-default-packages}.
142 @ref{Layout} for the presentation of the results.
147 @deffn {Command} debbugs-gnu-bugs &rest bugs
148 @deffnx {Command} debbugs-org-bugs &rest bugs
150 The commands @code{debbugs-gnu-bugs} and @code{debbugs-org-bugs} show
151 bugs specified by their bug number. Interactively, the bug numbers
152 must be entered as comma-separated list.
154 @ref{Layout} for the presentation of the results.
159 @deffn {Command} debbugs-gnu-patches
160 @deffnx {Command} debbugs-org-patches
162 The commands @code{debbugs-gnu-patches} and @code{debbugs-org-patches} show
163 all bugs tagged with @code{"patch"}. This is useful for bug triages.
165 @ref{Layout} for the presentation of the results.
171 @chapter Searching in the Debbugs Database.
173 The GNU Debbugs server allows text search in the database in the
174 messages submitted to the bugs. It uses a
175 @uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond,
176 HyperEstraier based search engine}@footnote{This has been added to the
177 Debbugs/SOAP backend of the GNU Debbugs server only.}.
179 @deffn {Command} debbugs-gnu-search
180 @deffnx {Command} debbugs-org-search
182 These both commands are completely interactive. They ask for a
183 @code{"search phrase"} for the text search. It is just a string which
184 contains the words to be searched for, combined by operators like AND,
185 ANDNOT and OR@. If there is no operator between the words, AND is
186 used by default. Only complete words, contained in a message body,
189 Wild card searches are also supported. It can be used for forward
190 match search and backward match search. For example, "[BW] euro"
191 matches words which begin with "euro". "[EW] sphere" matches words
192 which end with "sphere". Moreover, regular expressions are also
193 supported. For example, "[RX] ^inter.*al$" matches words which begin
194 with "inter" and end with "al".@footnote{Simplified forms, as
195 described in the Hyperestraier User Guide, are not supported.}
197 While the words to be searched for are case insensitive, the operators
198 must be specified case sensitive.
200 While the search for the phrase is performed only in the bodies of the
201 messages belonging to a bug report, it is also possible to
202 discriminate the search to further bug attributes. The commands ask
203 for such key-value pairs, until an empty key is returned. Possible
208 A comma-separated list of bug severities, @xref{Retrieving Bugs}.
211 A comma-separated list of defined software packages on the GNU Debbugs
212 server, @xref{Retrieving Bugs}.
215 A comma-separated list of defined user tags.
218 The email address of a message originator.
221 A time period the bug has been in which the bug has been submitted or
225 Word(s) the subject of the bug report contains.
228 The status of the bug report. Valid values are "open", "forwarded"
232 It is also possible to apply these commands with an empty search
233 phrase. In this case, the GNU Debbugs server is searched only for
234 bugs which fulfill the given attributes. The attributes to be applied
235 are the same as already described, plus
239 Whether archived bugs shall be searched (no value to be entered).
242 Bugs which belong to a given source, if that attribute has set.
245 An arbitrary string the bug is annotated with. Usually, this is the
246 same as the status mentioned above.
252 The email address of the bug's owner, submitter, maintainer, or
253 correspondent (somebody who has participated in bug messages).
259 The date of the last update, or the date of the bug report / bug fix.
262 The date the bug has been unarchived, if ever.
265 The email address of the worker who has closed the bug (if done).
268 A URL or an email address.
271 The message id of the initial bug report.
274 The summary of the bug report.
277 Not all of these attributes could be queried on the GNU Debbugs server
278 via the Debbugs/SOAP backend. In this case, the results of a query
279 are discriminated on the client side, which is indicated by the string
280 "(client-side filter)" in the minibuffer after the attribute name.
281 Note, that client side filters perform badly, because they could be
282 applied only after all bugs have been downloaded.
289 The commands described in the previous chapters generate (a) report
290 buffer(s) applicable for navigation. @code{debbugs-gnu-*} return a
291 tabulated list, and @code{debbugs-org-*} return a list of TODO items
295 * Tabulated Lists:: Tabulated Lists.
296 * TODO Items:: TODO Items.
297 * Control Messages:: Control Messages.
301 @node Tabulated Lists
302 @section Tabulated Lists
304 A tabulated list of bug reports consist of four columns for every bug
305 entry: @code{Id} (the bug number), @code{State} (some bug attributes),
306 @code{Submitter} (the name of the bug submitter), and @code{Title}
307 (the bug subject). Per default the bugs are sorted descending by
308 @code{Id}; this could be changed by clicking in the headline.
310 Different foreground colours present further information on the bug
311 report. If the bug number uses a red colour
312 (@code{debbugs-gnu-tagged}), the bug has been tagged locally. The
313 same face is used to mark bugs in the submitter or title column, when
314 the bug has been reported / is maintained by the user.
316 The bug state could appear in different colours: red
317 (@code{debbugs-gnu-new}, nobody has answered yet to this bug),
318 ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
319 recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
320 pending), orange (@code{debbugs-gnu-stale}, the bug has not been
321 touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
322 is closed). Archived bugs are shown with inverse face
323 (@code{debbugs-gnu-archived}).
325 The bug report buffers have enabled the minor
326 @code{debbugs-gnu-mode}. This enables the following key strokes:
328 @multitable @columnfractions .20 .80
331 @kindex @kbd{@key{RET}}
333 @kindex @kbd{@key{mouse-1}}
334 @kbd{@key{mouse-1}} @*
335 @kindex @kbd{@key{mouse-2}}
336 @kbd{@key{mouse-2}} @tab
337 @code{debbugs-gnu-select-report} @*
338 Show the email messages that discuss the bug.
343 @code{debbugs-gnu-display-status} @*
344 Show all bug attributes.
349 @code{debbugs-gnu-narrow-to-status} @*
350 Narrow the list of bugs to the bugs that match the given regex in
351 @code{State}, @code{Submitter} or @code{Title}.
356 @code{debbugs-gnu-show-all-blocking-reports} @*
357 Narrow the list of bug reports to the ones that are blocking the
363 @code{debbugs-gnu-widen} @*
364 Restore the full list again after narrowing.
369 @code{debbugs-gnu-rescan} @*
370 Reload all bugs. With a prefix argument @kbd{C-u}, the bug status
371 cache is disabled, and all bug reports are retrieved from the GNU
379 @code{debbugs-gnu-show-blocking-reports} @*
380 @code{debbugs-gnu-show-blocked-by-reports} @*
381 Show all bug reports which are blocking / blocked by this bug.
386 @code{debbugs-gnu-toggle-sort} @*
387 Toggle sorting order of bugs.
392 @code{debbugs-gnu-toggle-tag} @*
393 Toggle local tag of bugs.
398 @code{debbugs-gnu-toggle-suppress} @*
399 Toggle showing of closed bugs.
404 @code{debbugs-gnu-send-control-message} @*
405 Send a control message for this bug, @ref{Control Messages}.
409 @vindex debbugs-gnu-suppress-closed
410 The user option @code{debbugs-gnu-suppress-closed} controls, whether
411 closed bugs are shown in the initial list.
413 @vindex debbugs-gnu-mail-backend
414 The user option @code{debbugs-gnu-mail-backend} controls the
415 presentation of email messages produced by typing @kbd{@key{RET}} or
416 by clicking the mouse on a bug: if its value is @code{gnus}, the
417 default, a GNUS ephemeral group for that bug will be shown; if its
418 value is @code{rmail}, the command will present an Rmail folder
425 TODO items are offered as usual in @code{org-mode}. The bug
426 attributes are mapped onto properties of these items. They can be
427 shown by the usual navigation in @code{org-mode}.
429 Bug severities are mapped onto org severities, see
430 @code{debbugs-org-severity-priority}.
432 The bug report buffers have enabled the minor
433 @code{debbugs-org-mode}. This enables the following key strokes:
435 @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}
438 @kindex @kbd{@key{TAB}}
441 Outline the bug report attributes in @code{org-mode}.
444 @kindex @kbd{C-c # d}
446 @code{debbugs-gnu-display-status} @*
447 Show all bug attributes.
450 @kindex @kbd{C-c # t}
452 @code{debbugs-gnu-toggle-tag} @*
453 Toggle local tag of bugs.
456 @kindex @kbd{C-c # C}
458 @code{debbugs-gnu-send-control-message} @*
459 Send a control message for this bug, @ref{Control Messages}.
463 When the bug attributes are shown by @code{org-cycle}, there is a link
464 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
467 @node Control Messages
468 @section Control Messages
470 Debbugs control messages are sent by email to the GNU Debbugs control
471 server. Their format is described in
472 @uref{http://debbugs.gnu.org/server-control.html}.
474 A control message can be initiated in the tabulated list of bugs, in
475 the list of org TODO items, or in the GNUS ephemeral group or Rmail
476 folder opened for the messages belonging to a given bug. Control
477 messages can be sent to unarchived bugs only, in case a bug is
478 archived the control message @samp{unarchive} must be sent first.
480 In the minibuffer, the following control messages can be requested
481 (assuming that 12345 is the bug the control message is intended for).
482 The strings show the exact format of the control messages.
487 "block|unblock 12345 by 54321"
489 The second bug number is read interactively. It could be also a list
490 of comma-separated bug numbers.
495 The second argument, the Emacs version, is read interactively.
505 @itemx unreproducible
507 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
509 "tags 12345 patch|pending|security|unreproducible|wontfix"
513 @itemx doneunreproducible
515 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
518 The second argument in the close message, the Emacs version, is read
523 "forcemerge|merge 12345 54321"
525 The second bug number is read interactively.
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.
547 "retitle 12345 @var{title}"
549 The new bug title is read interactively.
556 "severity 12345 serious|important|normal|minor|wishlist"
565 "user @var{username}" @*
566 "usertag 12345 @var{tag}"
568 The username, read interactively, is either a package name or an email
569 address. The tag to be set is also read interactively.
576 Emacs uses @file{bug-reference.el} for adding hyperlinks to bugs in
577 files like @file{ChangeLog}, or in commentary sections of other files.
578 The reference to such bugs have a specialized format,
579 @uref{Bug#12345}. The hyperlinks are implemented as minor modes
580 @code{bug-reference-mode} and @code{bug-reference-prog-mode}.
582 @findex debbugs-browse-mode
583 @vindex debbugs-browse-function
584 This package adds a new minor mode @code{debbugs-browse-mode} on top
585 of them. Instead of using the default built-in Emacs browser for a
586 given bug reference, it opens a corresponding bug report buffer. The
587 customer option @code{debbugs-browse-function} controls, whether
588 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.
590 This minor mode is applicable for all URLs, not only bug references.
591 Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
592 shown in a bug report buffer, when @code{debbugs-browse-mode} is
597 @unnumbered Command Index
602 @unnumbered Variable Index
607 @unnumbered Key Index
613 @c bug-reference-url-format: "http://debbugs.gnu.org/%s"
614 @c eval: (bug-reference-mode)
615 @c eval: (debbugs-browse-mode)