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.
160 @chapter Searching in the Debbugs Database.
162 The GNU Debbugs server allows full text search in the database. It
164 @uref{http://fallabs.com/hyperestraier/uguide-en.html#searchcond,
165 HyperEstraier based search engine}@footnote{This has been added to the
166 Debbugs/SOAP backend of the GNU Debbugs server only.}.
168 @deffn {Command} debbugs-gnu-search
169 @deffnx {Command} debbugs-org-search
171 These both commands are completely interactive. They ask for a
172 @code{"search phrase"} for the full text search. It is just a string
173 which contains the words to be searched for, combined by operators
174 like AND, ANDNOT and OR. If there is no operator between the words,
175 AND is used by default.
177 Wild card searches are also supported. It can be used for forward
178 match search and backward match search. For example, "[BW] euro"
179 matches words which begin with "euro". "[EW] shere" matches words
180 which end with "sphere". Moreover, regular expressions are also
181 supported. For example, "[RX] ^inter.*al$" matches words which begin
182 with "inter" and end with "al".@footnote{Simplified forms, as
183 described in the Hyperestraier User Guide, are not supported.}
185 While the words to be searched for are case insensitive, the operators
186 must be specified case sensitive.
188 While the search for the phrase is performed only in the bodies of the
189 messages belonging to a bug report, it is also possible to
190 discriminate the search to further bug attributes. The commands ask
191 for such key-value pairs, until an empty key is returned. Possible
196 A comma-separated list of bug severities, @xref{Retrieving Bugs}.
199 A comma-separated list of defined software packages on the GNU Debbugs
200 server, @xref{Retrieving Bugs}.
203 A comma-separated list of defined user tags.
206 The email address of the bug submitter.
209 A time period the bug has been in which the bug has been submitted or
213 Word(s) the subject of the bug report contains.
216 The status of the bug report. Valid values are "done", "forwarded"
220 It is also possible to apply these commands with an empty search
221 phrase. In this case, the GNU Debbugs server is searched only for
222 bugs which fulfill the given attributes. The attributes to be applied
223 are the same as already described, plus
227 Whether archived bugs shall be searched (no value to be entered).
230 Bugs which belong to a given source, if that attribute has set.
233 An arbitrary string the bug is annotated with. Usually, this is the
234 same as the status mentioned above.
239 The email address of the bug's owner, maintainer, or correspondent
240 (somebody who has participated in bug messages).
246 The date of the last update, or the date of the bug report / bug fix.
249 The date the bug has been unarchived, if ever.
252 The email address of the worker who has closed the bug (if done).
255 A URL or an email address.
258 The message id of the initial bug report.
261 The summary of the bug report.
264 Not all of these attributes could be queried on the GNU Debbugs server
265 via the Debbugs/SOAP backend. In this case, the results of a query
266 are discriminated on the client side, which is indicated by the string
267 "(client-side filter)" in the minibuffer after the attribute name.
274 The commands described in the previous chapters generate (a) report
275 buffer(s) applicable for navigation. @code{debbugs-gnu-*} return a
276 tabulated list, and @code{debbugs-org-*} return a list of TODO items
280 * Tabulated Lists:: Tabulated Lists.
281 * TODO Items:: TODO Items.
282 * 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 descending by
293 @code{Id}; this could be changed by clicking in the headline.
295 Different foreground colours present further information on the bug
296 report. If the bug number uses a red colour
297 (@code{debbugs-gnu-tagged}), the bug has been tagged locally. The
298 same face is used to mark bugs in the submitter or title column, when
299 the bug has been reported / is maintained by the user.
301 The bug state could appear in different colours: red
302 (@code{debbugs-gnu-new}, nobody has answered yet to this bug),
303 ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
304 recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
305 pending), orange (@code{debbugs-gnu-stale}, the bug has not been
306 touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
307 is closed). Archived bugs are shown with inverse face
308 (@code{debbugs-gnu-archived}).
310 The bug report buffers have enabled the minor
311 @code{debbugs-gnu-mode}. This enables the following key strokes:
313 @multitable @columnfractions .20 .80
316 @kindex @kbd{@key{RET}}
318 @kindex @kbd{@key{mouse-1}}
319 @kbd{@key{mouse-1}} @*
320 @kindex @kbd{@key{mouse-2}}
321 @kbd{@key{mouse-2}} @tab
322 @code{debbugs-gnu-select-report} @*
323 Show the email messages that discuss the bug.
328 @code{debbugs-gnu-display-status} @*
329 Show all bug attributes.
334 @code{debbugs-gnu-narrow-to-status} @*
335 Narrow the list of bugs to the bugs that match the given regex in
336 @code{State}, @code{Submitter} or @code{Title}.
341 @code{debbugs-gnu-show-all-blocking-reports} @*
342 Narrow the list of bug reports to the ones that are blocking the
348 @code{debbugs-gnu-widen} @*
349 Restore the full list again after narrowing.
354 @code{debbugs-gnu-rescan} @*
355 Reload all bugs from the GNU Debbugs server.
362 @code{debbugs-gnu-show-blocking-reports} @*
363 @code{debbugs-gnu-show-blocked-by-reports} @*
364 Show all bug reports which are blocking / blocked by this bug.
369 @code{debbugs-gnu-toggle-sort} @*
370 Toggle sorting order of bugs.
375 @code{debbugs-gnu-toggle-tag} @*
376 Toggle local tag of bugs.
381 @code{debbugs-gnu-toggle-suppress} @*
382 Toggle showing of closed bugs.
387 @code{debbugs-gnu-send-control-message} @*
388 Send a control message for this bug, @ref{Control Messages}.
392 @vindex debbugs-gnu-mail-backend
393 The user option @code{debbugs-gnu-mail-backend} controls the
394 presentation of email messages produced by typing @kbd{@key{RET}} or
395 by clicking the mouse on a bug: if its value is @code{gnus}, the
396 default, a GNUS ephemeral group for that bug will be shown; if its
397 value is @code{rmail}, the command will present an Rmail folder
404 TODO items are offered as usual in @code{org-mode}. The bug
405 attributes are mapped onto properties of these items. They can be
406 shown by the usual navigation in @code{org-mode}.
408 Bug severities are mapped onto org severities, see
409 @code{debbugs-org-severity-priority}.
411 The bug report buffers have enabled the minor
412 @code{debbugs-org-mode}. This enables the following key strokes:
414 @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}
417 @kindex @kbd{@key{TAB}}
420 Outline the bug report attributes in @code{org-mode}.
423 @kindex @kbd{C-c # d}
425 @code{debbugs-gnu-display-status} @*
426 Show all bug attributes.
429 @kindex @kbd{C-c # t}
431 @code{debbugs-gnu-toggle-tag} @*
432 Toggle local tag of bugs.
435 @kindex @kbd{C-c # C}
437 @code{debbugs-gnu-send-control-message} @*
438 Send a control message for this bug, @ref{Control Messages}.
442 When the bug attributes are shown by @code{org-cycle}, there is a link
443 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
446 @node Control Messages
447 @section Control Messages
449 Debbugs control messages are sent by email to the GNU Debbugs control
450 server. Their format is described in
451 @uref{http://debbugs.gnu.org/server-control.html}.
453 A control message can be initiated in the tabulated list of bugs, in
454 the list of org TODO items, or in the GNUS ephemeral group or Rmail
455 folder opened for the messages belonging to a given bug. Control
456 messages can be sent to unarchived bugs only, in case a bug is
457 archived the control message @samp{unarchive} must be sent first.
459 In the minibuffer, the following control messages can be requested
460 (assuming that 12345 is the bug the control message is intended for).
461 The strings show the exact format of the control messages.
466 "block|unblock 12345 by 54321"
468 The second bug number is read interactively. It could be also a list
469 of comma-separated bug numbers.
474 The second argument, the Emacs version, is read interactively.
484 @itemx unreproducible
486 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
488 "tags 12345 patch|pending|security|unreproducible|wontfix"
492 @itemx doneunreproducible
494 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
497 The second argument in the close message, the Emacs version, is read
502 "forcemerge|merge 12345 54321"
504 The second bug number is read interactively.
511 "severity 12345 serious|important|normal|minor|wishlist"
514 "tags 12345 notabug" @*
515 "tags 12345 wontfix" @*
525 "reassign 12345 @var{package}"
527 The package name on the GNU Debbugs server is read interactively.
539 "user @var{username}" @*
540 "usertag 12345 @var{tag}"
542 The username, read interactively, is either a package name or an email
543 address. The tag to be set is also read interactively.
550 Emacs uses @file{bug-reference.el} for adding hyperlinks to bugs in
551 files like @file{ChangeLog}, or in commentary sections of other files.
552 The reference to such bugs have a specialized format,
553 @uref{Bug#12345}. The hyperlinks are implemented as minor modes
554 @code{bug-reference-mode} and @code{bug-reference-prog-mode}.
556 @findex debbugs-browse-mode
557 @vindex debbugs-browse-function
558 This package adds a new minor mode @code{debbugs-browse-mode} on top
559 of them. Instead of using the default built-in Emacs browser for a
560 given bug reference, it opens a corresponding bug report buffer. The
561 customer option @code{debbugs-browse-function} controls, whether
562 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} is called.
564 This minor mode is applicable for all URLs, not only bug references.
565 Any URL with the format @uref{http://debbugs.gnu.org/12345} will be
566 shown in a bug report buffer, when @code{debbugs-browse-mode} is
571 @unnumbered Command Index
576 @unnumbered Variable Index
581 @unnumbered Key Index
587 @c bug-reference-url-format: "http://debbugs.gnu.org/%s"
588 @c eval: (bug-reference-mode)
589 @c eval: (debbugs-browse-mode)