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 actually 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 to results are presented.
66 * Command Index:: Debbugs commands.
67 * Variable Index:: User options and variables.
68 * Key Index:: Keyboard strokes on bug report buffers.
72 @chapter Retrieving Bugs
74 Bugs are retrieved by the @code{debbugs-gnu} or @code{debbugs-org}
75 commands. In their simple version, they retrieve just bugs for the
76 @code{"emacs"} package on the GNU Debbugs server, filtered by bug
77 severities. Further filtering is possible when the commands are
80 When the bug numbers to be retrieved are known, the commands
81 @code{debbugs-gnu-bugs} or @code{debbugs-org-bugs} are applicable.
84 @deffn {Command} debbugs-gnu severities &optional packages archivedp suppress tags
85 @deffnx {Command} debbugs-org severities &optional packages archivedp suppress tags
87 These commands retrieve bug reports from the GNU Debbugs server.
88 @code{debbugs-gnu} returns a tabulated list, and @code{debbugs-org}
89 returns a list of TODO items in @code{org-mode}. If there were more
90 than @code{debbugs-gnu-default-hits-per-page} bug results from the
91 query, there are widgets (@code{debbugs-gnu}) or links
92 (@code{debbugs-org}) in the result buffer for retrieving the other
95 @vindex debbugs-gnu-all-severities
96 @var{severities} is a list of strings which filter for the severities
97 of the bugs to be retrieved. Valid severities are @code{"serious"},
98 @code{"important"}, @code{"normal"}, @code{"minor"} and
99 @code{"wishlist"} (see also the constant
100 @code{debbugs-gnu-all-severities}). If the list is empty, there is no
101 filtering with respect to severities. The keyword @code{"tagged"},
102 which is also possible, is not a severity in the GNU Debbugs server
103 but allows to restrict the result to bugs with a given user tag.
105 @vindex debbugs-gnu-all-packages
106 @var{packages}, also a list of strings, point to the defined software
107 packages on the GNU Debbugs server which shall be taken into account.
108 The existing package names are compiled into the constant
109 @code{debbugs-gnu-all-packages}.
111 @var{archivedp}, if non-@code{nil}, extends the result also on
112 archived bugs on the GNU Debbugs server.
114 @var{suppress} shall also distinct between @code{nil} and
115 non-@code{nil}. When non-@code{nil}, closed bugs are suppressed from
118 When @var{severities} contains the severity @code{"tagged"},
119 @var{tags} is consulted in order to restrict the result on bugs which
120 are tagged with one of the strings of the list @var{tags}. This list
121 can also be empty; in this case locally tagged bugs are included into
124 Called interactively, the commands require just the @var{severities}
125 and the @var{tags} (if @var{severities} includes @code{"tagged"}). In
126 order to provide the other arguments interactively, the commands must
127 be called with a prefix, like @kbd{C-u M-x debbugs-gnu}. In the
128 minibuffer, lists must be entered comma-separated.
130 @vindex debbugs-gnu-default-severities
131 @vindex debbugs-gnu-default-packages
132 Default values for interactive use could be configured in the customer
133 options @code{debbugs-gnu-default-severities} and
134 @code{debbugs-gnu-default-packages}.
136 @vindex debbugs-gnu-default-hits-per-page
137 When the result would exceed more than 500 bugs, the user is asked how
138 many bugs to retrieve at once. This value can be configured in the
139 customer option @code{debbugs-gnu-default-hits-per-page}. However, it
140 is not recommended to exceeds the default value.
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 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.
285 @node Tabulated Lists
286 @section Tabulated Lists
288 A tabulated list of bug reports consist of four columns for every bug
289 entry: @code{Id} (the bug number), @code{State} (some bug attributes),
290 @code{Submitter} (the name of the bug submitter), and @code{Title}
291 (the bug subject). Per default the bugs are sorted by @code{Id}; this
292 could be changed by clicking in the headline.
294 Per bug retrieval only up to 500
295 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
296 presented in a buffer. If there shall be presented more bugs, widgets
297 are placed on the top and bottom of the buffer for navigation to
298 further report buffers.
300 Different foreground colours present further information on the bug
301 report. If the bug number uses a red colour
302 (@code{debbugs-gnu-tagged}), the bug has been tagged locally. The
303 same face is used to mark bugs in the submitter or title column, when
304 the bug has been reported / is maintained by the user.
306 The bug state could appear in different colours: red
307 (@code{debbugs-gnu-new}, nobody has answered yet to this bug),
308 ForestGreen (@code{debbugs-gnu-handled}, the bug has been modified
309 recently), MidnightBlue (@code{debbugs-gnu-pending}, the bug is
310 pending), orange (@code{debbugs-gnu-stale}, the bug has not been
311 touched for a while), and DarkGrey (@code{debbugs-gnu-done}, the bug
314 The bug report buffers have enabled the minor
315 @code{debbugs-gnu-mode}. This enables the following key strokes:
317 @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}
320 @kindex @kbd{@key{RET}}
322 @kindex @kbd{@key{mouse-1}}
324 @kindex @kbd{@key{mouse-2}}
325 @kbd{@key{mouse-2}} @tab
326 @code{debbugs-gnu-select-report} @*
327 Open a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
332 @code{debbugs-gnu-display-status} @*
333 Show all bug attributes.
338 @c @code{debbugs-gnu-narrow-to-status}
343 @c @code{debbugs-gnu-widen}
348 @code{debbugs-gnu-rescan} @*
349 Reload all bugs from the GNU Debbugs server.
354 @code{debbugs-gnu-show-blocking-reports}
358 @code{debbugs-gnu-show-blocked-by-reports} @*
359 Show all bug reports which are blocking / blocked by this bug.
364 @code{debbugs-gnu-toggle-sort} @*
365 Toggle sorting order of bugs.
370 @code{debbugs-gnu-toggle-tag} @*
371 Toggle local tag of bugs.
376 @code{debbugs-gnu-toggle-suppress} @*
377 Toggle showing of closed bugs.
382 @code{debbugs-gnu-send-control-message} @*
383 Send a control message for this bug, @ref{Control Messages}.
391 TODO items are offered as usual in @code{org-mode}. The bug
392 attributes are mapped onto properties of these items. They can be
393 shown by the usual navigation in @code{org-mode}.
395 Per bug retrieval only up to 500
396 (@code{debbugs-gnu-default-hits-per-page}) bugs are retrieved and
397 presented in a buffer. At the end of the buffer there is a link,
398 which allows to append the next 500 bugs to the list.
400 Bug severities are mapped onto org severities, see
401 @code{debbugs-org-severity-priority}.
403 The bug report buffers have enabled the minor
404 @code{debbugs-gnu-mode}. This enables the following key strokes:
406 @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}
409 @kindex @kbd{@key{TAB}}
412 Outline the bug report attributes in @code{org-mode}.
415 @kindex @kbd{C-c # d}
417 @code{debbugs-gnu-display-status} @*
418 Show all bug attributes.
421 @kindex @kbd{C-c # t}
423 @code{debbugs-gnu-toggle-tag} @*
424 Toggle local tag of bugs.
427 @kindex @kbd{C-c # C}
429 @code{debbugs-gnu-send-control-message} @*
430 Send a control message for this bug, @ref{Control Messages}.
434 When the bug attributes are shown by @code{org-cycle}, there is a link
435 @code{Messages} which opens a GNUS ephemeral group for that bug.@c (@pxref{xxx}).
438 @node Control Messages
439 @section Control Messages
441 Debbugs control messages are sent by email to the GNU Debbugs control
442 server. Their format is described in
443 @uref{http://debbugs.gnu.org/server-control.html}.
445 A control message can be initiated in the tabulated list of bugs, in
446 the list of org TODO items, or in the GNUS ephemeral group opened for
447 the messages belonging to a given bug. In the minibuffer, the
448 following control messages can be requested (assuming that 12345 is
449 the bug the control message is intended for). The strings show the
450 exact format of the control messages.
455 "block|unblock 12345 by 54321"
457 The second bug number is read interactively. It could be also a list
458 of comma-separated bug numbers.
463 The second argument, the Emacs version, is read interactively.
473 @itemx unreproducible
475 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
477 "tags 12345 patch|pending|security|unreproducible|wontfix"
481 @itemx doneunreproducible
483 "tags 12345 fixed|notabug|unreproducible|wontfix" @*
486 The second argument in the close message, the Emacs version, is read
491 "forcemerge|merge 12345 54321"
493 The second bug number is read interactively.
500 "severity 12345 important|minor|normal|serious|wishlist"
503 "tags 12345 notabug" @*
504 "tags 12345 wontfix" @*
514 "reassign 12345 @var{package}"
516 The package name on the GNU Debbugs server is read interactively.
528 "user @var{username}" @*
529 "usertag 12345 @var{tag}"
531 The username, read interactively, is either a package name or an email
532 address. The tag to be set is also read interactively.
537 @unnumbered Command Index
542 @unnumbered Variable Index
547 @unnumbered Key Index