1 This is debbugs-ug.info, produced by makeinfo version 6.0 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.
140 File: debbugs-ug.info, Node: Searching Bugs, Next: Layout, Prev: Retrieving Bugs, Up: Top
142 2 Searching in the Debbugs Database.
143 ************************************
145 The GNU Debbugs server allows full text search in the database. It
146 uses a HyperEstraier based search engine
147 (http://fallabs.com/hyperestraier/uguide-en.html#searchcond)(1).
149 -- Command: debbugs-gnu-search
150 -- Command: debbugs-org-search
152 These both commands are completely interactive. They ask for a
153 '"search phrase"' for the full text search. It is just a string
154 which contains the words to be searched for, combined by
155 operators like AND, ANDNOT and OR. If there is no operator
156 between the words, AND is used by default.
158 Wild card searches are also supported. It can be used for
159 forward match search and backward match search. For example,
160 "[BW] euro" matches words which begin with "euro". "[EW] shere"
161 matches words which end with "sphere". Moreover, regular
162 expressions are also supported. For example, "[RX] ^inter.*al$"
163 matches words which begin with "inter" and end with "al".(2)
165 While the words to be searched for are case insensitive, the
166 operators must be specified case sensitive.
168 While the search for the phrase is performed only in the bodies
169 of the messages belonging to a bug report, it is also possible to
170 discriminate the search to further bug attributes. The commands
171 ask for such key-value pairs, until an empty key is returned.
172 Possible attributes are
175 A comma-separated list of bug severities, *Note Retrieving
179 A comma-separated list of defined software packages on the
180 GNU Debbugs server, *Note Retrieving Bugs::.
183 A comma-separated list of defined user tags.
186 The email address of the bug submitter.
189 A time period the bug has been in which the bug has been
190 submitted or modified.
193 Word(s) the subject of the bug report contains.
196 The status of the bug report. Valid values are "done",
197 "forwarded" and "open".
199 It is also possible to apply these commands with an empty search
200 phrase. In this case, the GNU Debbugs server is searched only
201 for bugs which fulfill the given attributes. The attributes to
202 be applied are the same as already described, plus
205 Whether archived bugs shall be searched (no value to be
209 Bugs which belong to a given source, if that attribute has
213 An arbitrary string the bug is annotated with. Usually,
214 this is the same as the status mentioned above.
219 The email address of the bug's owner, maintainer, or
220 correspondent (somebody who has participated in bug
227 The date of the last update, or the date of the bug report /
231 The date the bug has been unarchived, if ever.
234 The email address of the worker who has closed the bug (if
238 A URL or an email address.
241 The message id of the initial bug report.
244 The summary of the bug report.
246 Not all of these attributes could be queried on the GNU Debbugs
247 server via the Debbugs/SOAP backend. In this case, the results
248 of a query are discriminated on the client side, which is
249 indicated by the string "(client-side filter)" in the minibuffer
250 after the attribute name.
252 ---------- Footnotes ----------
254 (1) This has been added to the Debbugs/SOAP backend of the GNU
257 (2) Simplified forms, as described in the Hyperestraier User Guide,
261 File: debbugs-ug.info, Node: Layout, Next: Minor Mode, Prev: Searching Bugs, Up: Top
266 The commands described in the previous chapters generate (a) report
267 buffer(s) applicable for navigation. 'debbugs-gnu-*' return a
268 tabulated list, and 'debbugs-org-*' return a list of TODO items in
273 * Tabulated Lists:: Tabulated Lists.
274 * TODO Items:: TODO Items.
275 * Control Messages:: Control Messages.
278 File: debbugs-ug.info, Node: Tabulated Lists, Next: TODO Items, Up: Layout
283 A tabulated list of bug reports consist of four columns for every bug
284 entry: 'Id' (the bug number), 'State' (some bug attributes),
285 'Submitter' (the name of the bug submitter), and 'Title' (the bug
286 subject). Per default the bugs are sorted descending by 'Id'; this
287 could be changed by clicking in the headline.
289 Different foreground colours present further information on the bug
290 report. If the bug number uses a red colour ('debbugs-gnu-tagged'),
291 the bug has been tagged locally. The same face is used to mark bugs
292 in the submitter or title column, when the bug has been reported / is
293 maintained by the user.
295 The bug state could appear in different colours: red
296 ('debbugs-gnu-new', nobody has answered yet to this bug), ForestGreen
297 ('debbugs-gnu-handled', the bug has been modified recently),
298 MidnightBlue ('debbugs-gnu-pending', the bug is pending), orange
299 ('debbugs-gnu-stale', the bug has not been touched for a while), and
300 DarkGrey ('debbugs-gnu-done', the bug is closed). Archived bugs are
301 shown with inverse face ('debbugs-gnu-archived').
303 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
304 This enables the following key strokes:
306 '<RET>' 'debbugs-gnu-select-report'
307 '<mouse-1>' Show the email messages that discuss the bug.
310 'd' 'debbugs-gnu-display-status'
311 Show all bug attributes.
313 '/' 'debbugs-gnu-narrow-to-status'
314 Narrow the list of bugs to the bugs that match the
315 given regex in 'State', 'Submitter' or 'Title'.
317 'R' 'debbugs-gnu-show-all-blocking-reports'
318 Narrow the list of bug reports to the ones that are
319 blocking the current release.
321 'w' 'debbugs-gnu-widen'
322 Restore the full list again after narrowing.
324 'g' 'debbugs-gnu-rescan'
325 Reload all bugs from the GNU Debbugs server.
327 'B' 'debbugs-gnu-show-blocking-reports'
328 'b' 'debbugs-gnu-show-blocked-by-reports'
329 Show all bug reports which are blocking / blocked by
332 's' 'debbugs-gnu-toggle-sort'
333 Toggle sorting order of bugs.
335 't' 'debbugs-gnu-toggle-tag'
336 Toggle local tag of bugs.
338 'x' 'debbugs-gnu-toggle-suppress'
339 Toggle showing of closed bugs.
341 'C' 'debbugs-gnu-send-control-message'
342 Send a control message for this bug,
343 *note Control Messages::.
346 The user option 'debbugs-gnu-mail-backend' controls the
347 presentation of email messages produced by typing '<RET>' or by
348 clicking the mouse on a bug: if its value is 'gnus', the default, a
349 GNUS ephemeral group for that bug will be shown; if its value is
350 'rmail', the command will present an Rmail folder instead.
353 File: debbugs-ug.info, Node: TODO Items, Next: Control Messages, Prev: Tabulated Lists, Up: Layout
358 TODO items are offered as usual in 'org-mode'. The bug attributes are
359 mapped onto properties of these items. They can be shown by the usual
360 navigation in 'org-mode'.
362 Bug severities are mapped onto org severities, see
363 'debbugs-org-severity-priority'.
365 The bug report buffers have enabled the minor 'debbugs-org-mode'.
366 This enables the following key strokes:
369 Outline the bug report attributes in 'org-mode'.
371 'C-c # d' 'debbugs-gnu-display-status'
372 Show all bug attributes.
374 'C-c # t' 'debbugs-gnu-toggle-tag'
375 Toggle local tag of bugs.
377 'C-c # C' 'debbugs-gnu-send-control-message'
378 Send a control message for this bug, *note Control Messages::.
381 When the bug attributes are shown by 'org-cycle', there is a link
382 'Messages' which opens a GNUS ephemeral group for that bug.
385 File: debbugs-ug.info, Node: Control Messages, Prev: TODO Items, Up: Layout
390 Debbugs control messages are sent by email to the GNU Debbugs control
391 server. Their format is described in
392 <http://debbugs.gnu.org/server-control.html>.
394 A control message can be initiated in the tabulated list of bugs,
395 in the list of org TODO items, or in the GNUS ephemeral group or Rmail
396 folder opened for the messages belonging to a given bug. Control
397 messages can be sent to unarchived bugs only, in case a bug is
398 archived the control message 'unarchive' must be sent first.
400 In the minibuffer, the following control messages can be requested
401 (assuming that 12345 is the bug the control message is intended for).
402 The strings show the exact format of the control messages.
406 "block|unblock 12345 by 54321"
408 The second bug number is read interactively. It could be also a
409 list of comma-separated bug numbers.
414 The second argument, the Emacs version, is read interactively.
426 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
428 "tags 12345 patch|pending|security|unreproducible|wontfix"
434 "tags 12345 fixed|notabug|unreproducible|wontfix"
437 The second argument in the close message, the Emacs version, is
442 "forcemerge|merge 12345 54321"
444 The second bug number is read interactively.
451 "severity 12345 serious|important|normal|minor|wishlist"
465 "reassign 12345 PACKAGE"
467 The package name on the GNU Debbugs server is read interactively.
482 The username, read interactively, is either a package name or an
483 email address. The tag to be set is also read interactively.
486 File: debbugs-ug.info, Node: Minor Mode, Next: Command Index, Prev: Layout, Up: Top
491 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
492 like 'ChangeLog', or in commentary sections of other files. The
493 reference to such bugs have a specialized format, <Bug#12345>. The
494 hyperlinks are implemented as minor modes 'bug-reference-mode' and
495 'bug-reference-prog-mode'.
497 This package adds a new minor mode 'debbugs-browse-mode' on top of
498 them. Instead of using the default built-in Emacs browser for a given
499 bug reference, it opens a corresponding bug report buffer. The
500 customer option 'debbugs-browse-function' controls, whether
501 'debbugs-gnu-bugs' or 'debbugs-org-bugs' is called.
503 This minor mode is applicable for all URLs, not only bug
504 references. Any URL with the format <http://debbugs.gnu.org/12345>
505 will be shown in a bug report buffer, when 'debbugs-browse-mode' is
509 File: debbugs-ug.info, Node: Command Index, Next: Variable Index, Prev: Minor Mode, Up: Top