1 This is debbugs-ug.info, produced by makeinfo version 6.1 from
4 Copyright (C) 2015-2016 Free Software Foundation, Inc.
6 Permission is granted to copy, distribute and/or modify this
7 document under the terms of the GNU Free Documentation License,
8 Version 1.2 or any later version published by the Free Software
9 Foundation; with no Invariant Sections, with the Front-Cover, or
10 Back-Cover Texts. A copy of the license is included in the
11 section entitled "GNU Free Documentation License" in the Emacs
14 This document is part of a collection distributed under the GNU
15 Free Documentation License. If you want to distribute this
16 document separately from the collection, you can do so by adding
17 a copy of the license to the document, as described in section 6
20 All Emacs Lisp code contained in this document may be used,
21 distributed, and modified without restriction.
22 INFO-DIR-SECTION Emacs
24 * Debbugs UG: (debbugs-ug). Debbugs User Interface in Emacs.
28 File: debbugs-ug.info, Node: Top, Next: Retrieving Bugs, Up: (dir)
33 Debbugs is a bugtracking system (BTS) that was initially written for
34 the Debian project but currently used also by the GNU project. The
35 main distinctive feature of Debbugs is that it's mostly email-based.
36 All actions on bug reports: opening, closing, changing the status,
37 commenting, forwarding are performed via email by sending specially
38 composed letters to the particular email addresses. However,
39 searching the bug reports, querying bug report status and viewing
40 comments have been web-based for a long time. To overcome this
41 inconvenience the Debbugs/SOAP service was introduced.
43 Based on the Debbugs/SOAP service, frontends are written which
44 offer handling of bugs inside Emacs. These frontends are restricted
45 to the GNU Debbugs server. Bugs are presented either as tabulated
46 list ('debbugs-gnu') or as 'org-mode' TODO list ('debbugs-org', *note
47 Org Mode: (org)Top.). As backend they use the 'debbugs' Emacs library
48 (*note Debbugs Programmer's Manual: (debbugs)Top.).
52 * Retrieving Bugs:: How to retrieve bugs.
53 * Searching Bugs:: How to search in the debbugs database.
54 * Layout:: How the results are presented.
55 * Minor Mode:: How to use browse bug URLs.
57 * Command Index:: Debbugs commands.
58 * Variable Index:: User options and variables.
59 * Key Index:: Keyboard strokes on bug report buffers.
62 File: debbugs-ug.info, Node: Retrieving Bugs, Next: Searching Bugs, Prev: Top, Up: Top
67 Bugs are retrieved by the 'debbugs-gnu' or 'debbugs-org' commands. In
68 their simple version, they retrieve just bugs for the '"emacs"'
69 package on the GNU Debbugs server, filtered by bug severities.
70 Further filtering is possible when the commands are called with a
73 When the bug numbers to be retrieved are known, the commands
74 'debbugs-gnu-bugs' or 'debbugs-org-bugs' are applicable.
76 -- Command: debbugs-gnu severities &optional packages archivedp
78 -- Command: debbugs-org severities &optional packages archivedp
81 These commands retrieve bug reports from the GNU Debbugs server.
82 'debbugs-gnu' returns a tabulated list, and 'debbugs-org' returns
83 a list of TODO items in 'org-mode'. In order not to stress the
84 GNU Debbugs server, the bugs are retrieved in chunks of 500 bugs.
85 However, the bug report buffer shows all retrieved bugs then, in
86 reverse bug number order.
88 SEVERITIES is a list of strings which filter for the severities
89 of the bugs to be retrieved. Valid severities are '"serious"',
90 '"important"', '"normal"', '"minor"' and '"wishlist"' (see also
91 the constant 'debbugs-gnu-all-severities'). If the list is
92 empty, there is no filtering with respect to severities. The
93 keyword '"tagged"', which is also possible, is not a severity in
94 the GNU Debbugs server but allows to restrict the result to bugs
95 with a given user tag.
97 PACKAGES, also a list of strings, point to the defined software
98 packages on the GNU Debbugs server which shall be taken into
99 account. The existing package names are compiled into the
100 constant 'debbugs-gnu-all-packages'.
102 ARCHIVEDP, if non-'nil', extends the result also on archived bugs
103 on the GNU Debbugs server.
105 SUPPRESS shall also distinct between 'nil' and non-'nil'. When
106 non-'nil', closed bugs are suppressed from being retrieved from
107 the Debbugs server. Which bugs are regarded as suppressed is
108 configured in the customer option 'debbugs-gnu-suppress-bugs'.
109 Per default, bugs marked as '"done"' are suppressed from being
112 When SEVERITIES contains the severity '"tagged"', TAGS is
113 consulted in order to restrict the result on bugs which are
114 tagged with one of the strings of the list TAGS. This list can
115 also be empty; in this case locally tagged bugs are included into
118 Called interactively, the commands require just the SEVERITIES
119 and the TAGS (if SEVERITIES includes '"tagged"'). In order to
120 provide the other arguments interactively, the commands must be
121 called with a prefix, like 'C-u M-x debbugs-gnu'. In the
122 minibuffer, lists must be entered comma-separated.
124 Default values for interactive use could be configured in the
125 customer options 'debbugs-gnu-default-severities' and
126 'debbugs-gnu-default-packages'.
128 *note Layout:: for the presentation of the results.
130 -- Command: debbugs-gnu-bugs &rest bugs
131 -- Command: debbugs-org-bugs &rest bugs
133 The commands 'debbugs-gnu-bugs' and 'debbugs-org-bugs' show bugs
134 specified by their bug number. Interactively, the bug numbers
135 must be entered as comma-separated list.
137 *note Layout:: for the presentation of the results.
139 -- Command: debbugs-gnu-patches
140 -- Command: debbugs-org-patches
142 The commands 'debbugs-gnu-patches' and 'debbugs-org-patches' show
143 all bugs tagged with '"patch"'. This is useful for bug triages.
145 *note Layout:: for the presentation of the results.
148 File: debbugs-ug.info, Node: Searching Bugs, Next: Layout, Prev: Retrieving Bugs, Up: Top
150 2 Searching in the Debbugs Database.
151 ************************************
153 The GNU Debbugs server allows text search in the database in the
154 messages submitted to the bugs. It uses a HyperEstraier based search
156 (http://fallabs.com/hyperestraier/uguide-en.html#searchcond)(1).
158 -- Command: debbugs-gnu-search
159 -- Command: debbugs-org-search
161 These both commands are completely interactive. They ask for a
162 '"search phrase"' for the text search. It is just a string which
163 contains the words to be searched for, combined by operators like
164 AND, ANDNOT and OR. If there is no operator between the words,
165 AND is used by default. Only complete words, contained in a
166 message body, are searched for.
168 Wild card searches are also supported. It can be used for
169 forward match search and backward match search. For example,
170 "[BW] euro" matches words which begin with "euro". "[EW] sphere"
171 matches words which end with "sphere". Moreover, regular
172 expressions are also supported. For example, "[RX] ^inter.*al$"
173 matches words which begin with "inter" and end with "al".(2)
175 While the words to be searched for are case insensitive, the
176 operators must be specified case sensitive.
178 While the search for the phrase is performed only in the bodies
179 of the messages belonging to a bug report, it is also possible to
180 discriminate the search to further bug attributes. The commands
181 ask for such key-value pairs, until an empty key is returned.
182 Possible attributes are
185 A comma-separated list of bug severities, *Note Retrieving
189 A comma-separated list of defined software packages on the
190 GNU Debbugs server, *Note Retrieving Bugs::.
193 A comma-separated list of defined user tags.
196 The email address of a message originator.
199 A time period the bug has been in which the bug has been
200 submitted or modified.
203 Word(s) the subject of the bug report contains.
206 The status of the bug report. Valid values are "pending",
207 "forwarded", "fixed" and "done".
209 It is also possible to apply these commands with an empty search
210 phrase. In this case, the GNU Debbugs server is searched only
211 for bugs which fulfill the given attributes. The attributes to
212 be applied are the same as already described, plus
215 Whether archived bugs shall be searched (no value to be
219 Bugs which belong to a given source, if that attribute has
223 An arbitrary string the bug is annotated with. Usually,
224 this is the same as the status mentioned above.
230 The email address of the bug's owner, submitter, maintainer,
231 or correspondent (somebody who has participated in bug
238 The date of the last update, or the date of the bug report /
242 The date the bug has been unarchived, if ever.
245 The email address of the worker who has closed the bug (if
249 A URL or an email address.
252 The message id of the initial bug report.
255 The summary of the bug report.
257 Not all of these attributes could be queried on the GNU Debbugs
258 server via the Debbugs/SOAP backend. In this case, the results
259 of a query are discriminated on the client side, which is
260 indicated by the string "(client-side filter)" in the minibuffer
261 after the attribute name. Note, that client side filters perform
262 badly, because they could be applied only after all bugs have
265 ---------- Footnotes ----------
267 (1) This has been added to the Debbugs/SOAP backend of the GNU
270 (2) Simplified forms, as described in the Hyperestraier User Guide,
274 File: debbugs-ug.info, Node: Layout, Next: Minor Mode, Prev: Searching Bugs, Up: Top
279 The commands described in the previous chapters generate (a) report
280 buffer(s) applicable for navigation. 'debbugs-gnu-*' return a
281 tabulated list, and 'debbugs-org-*' return a list of TODO items in
286 * Tabulated Lists:: Tabulated Lists.
287 * TODO Items:: TODO Items.
288 * Control Messages:: Control Messages.
291 File: debbugs-ug.info, Node: Tabulated Lists, Next: TODO Items, Up: Layout
296 A tabulated list of bug reports consist of four columns for every bug
297 entry: 'Id' (the bug number), 'State' (some bug attributes),
298 'Submitter' (the name of the bug submitter), and 'Title' (the bug
299 subject). Per default the bugs are sorted descending by 'Id'; this
300 could be changed by clicking in the headline.
302 Different foreground colours present further information on the bug
303 report. If the bug number uses a red colour ('debbugs-gnu-tagged'),
304 the bug has been tagged locally. The same face is used to mark bugs
305 in the submitter or title column, when the bug has been reported / is
306 maintained by the user.
308 The bug state could appear in different colours: red
309 ('debbugs-gnu-new', nobody has answered yet to this bug), ForestGreen
310 ('debbugs-gnu-handled', the bug has been modified recently),
311 MidnightBlue ('debbugs-gnu-pending', the bug is pending), orange
312 ('debbugs-gnu-stale', the bug has not been touched for a while), and
313 DarkGrey ('debbugs-gnu-done', the bug is closed). Archived bugs are
314 shown with inverse face ('debbugs-gnu-archived').
316 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
317 This enables the following key strokes:
319 '<RET>' 'debbugs-gnu-select-report'
320 '<mouse-1>' Show the email messages that discuss the bug.
323 'd' 'debbugs-gnu-display-status'
324 Show all bug attributes.
326 '/' 'debbugs-gnu-narrow-to-status'
327 Narrow the list of bugs to the bugs that match the
328 given regex in 'State', 'Submitter' or 'Title'.
330 'R' 'debbugs-gnu-show-all-blocking-reports'
331 Narrow the list of bug reports to the ones that are
332 blocking the current release.
334 'w' 'debbugs-gnu-widen'
335 Restore the full list again after narrowing.
337 'g' 'debbugs-gnu-rescan'
338 Reload all bugs. With a prefix argument 'C-u', the
339 bug status cache is disabled, and all bug reports are
340 retrieved from the GNU Debbugs server.
342 'B' 'debbugs-gnu-show-blocking-reports'
343 'b' 'debbugs-gnu-show-blocked-by-reports'
344 Show all bug reports which are blocking / blocked by
347 's' 'debbugs-gnu-toggle-sort'
348 Toggle sorting order of bugs.
350 't' 'debbugs-gnu-toggle-tag'
351 Toggle local tag of bugs.
353 'x' 'debbugs-gnu-toggle-suppress'
354 Toggle showing of closed bugs.
356 'C' 'debbugs-gnu-send-control-message'
357 Send a control message for this bug,
358 *note Control Messages::.
361 The user option 'debbugs-gnu-suppress-closed' controls, whether
362 closed bugs are shown in the initial list.
364 The user option 'debbugs-gnu-mail-backend' controls the
365 presentation of email messages produced by typing '<RET>' or by
366 clicking the mouse on a bug: if its value is 'gnus', the default, a
367 GNUS ephemeral group for that bug will be shown; if its value is
368 'rmail', the command will present an Rmail folder instead.
371 File: debbugs-ug.info, Node: TODO Items, Next: Control Messages, Prev: Tabulated Lists, Up: Layout
376 TODO items are offered as usual in 'org-mode'. The bug attributes are
377 mapped onto properties of these items. They can be shown by the usual
378 navigation in 'org-mode'.
380 Bug severities are mapped onto org severities, see
381 'debbugs-org-severity-priority'.
383 The bug report buffers have enabled the minor 'debbugs-org-mode'.
384 This enables the following key strokes:
387 Outline the bug report attributes in 'org-mode'.
389 'C-c # d' 'debbugs-gnu-display-status'
390 Show all bug attributes.
392 'C-c # t' 'debbugs-gnu-toggle-tag'
393 Toggle local tag of bugs.
395 'C-c # C' 'debbugs-gnu-send-control-message'
396 Send a control message for this bug, *note Control Messages::.
399 When the bug attributes are shown by 'org-cycle', there is a link
400 'Messages' which opens a GNUS ephemeral group for that bug.
403 File: debbugs-ug.info, Node: Control Messages, Prev: TODO Items, Up: Layout
408 Debbugs control messages are sent by email to the GNU Debbugs control
409 server. Their format is described in
410 <http://debbugs.gnu.org/server-control.html>.
412 A control message can be initiated in the tabulated list of bugs,
413 in the list of org TODO items, or in the GNUS ephemeral group or Rmail
414 folder opened for the messages belonging to a given bug. Control
415 messages can be sent to unarchived bugs only, in case a bug is
416 archived the control message 'unarchive' must be sent first.
418 In the minibuffer, the following control messages can be requested
419 (assuming that 12345 is the bug the control message is intended for).
420 The strings show the exact format of the control messages.
424 "block|unblock 12345 by 54321"
426 The second bug number is read interactively. It could be also a
427 list of comma-separated bug numbers.
432 The second argument, the Emacs version, is read interactively.
444 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
446 "tags 12345 patch|pending|security|unreproducible|wontfix"
452 "tags 12345 fixed|notabug|unreproducible|wontfix"
455 The second argument in the close message, the Emacs version, is
460 "forcemerge|merge 12345 54321"
462 The second bug number is read interactively.
476 "reassign 12345 PACKAGE"
478 The package name on the GNU Debbugs server is read interactively.
484 "retitle 12345 TITLE"
486 The new bug title is read interactively.
493 "severity 12345 serious|important|normal|minor|wishlist"
505 The username, read interactively, is either a package name or an
506 email address. The tag to be set is also read interactively.
509 File: debbugs-ug.info, Node: Minor Mode, Next: Command Index, Prev: Layout, Up: Top
514 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
515 like 'ChangeLog', or in commentary sections of other files. The
516 reference to such bugs have a specialized format, <Bug#12345>. The
517 hyperlinks are implemented as minor modes 'bug-reference-mode' and
518 'bug-reference-prog-mode'.
520 This package adds a new minor mode 'debbugs-browse-mode' on top of
521 them. Instead of using the default built-in Emacs browser for a given
522 bug reference, it opens a corresponding bug report buffer. The
523 customer option 'debbugs-browse-function' controls, whether
524 'debbugs-gnu-bugs' or 'debbugs-org-bugs' is called.
526 This minor mode is applicable for all URLs, not only bug
527 references. Any URL with the format <http://debbugs.gnu.org/12345>
528 will be shown in a bug report buffer, when 'debbugs-browse-mode' is
532 File: debbugs-ug.info, Node: Command Index, Next: Variable Index, Prev: Minor Mode, Up: Top