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 mail addresses. However, searching
39 the bug reports, querying bug report status and viewing comments have
40 been web-based for a long time. To overcome this inconvenience the
41 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'. If there were more than
84 'debbugs-gnu-default-hits-per-page' bug results from the query,
85 there are widgets ('debbugs-gnu') or links ('debbugs-org') in the
86 result buffer for retrieving the other results.
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 the results.
108 When SEVERITIES contains the severity '"tagged"', TAGS is
109 consulted in order to restrict the result on bugs which are
110 tagged with one of the strings of the list TAGS. This list can
111 also be empty; in this case locally tagged bugs are included into
114 Called interactively, the commands require just the SEVERITIES
115 and the TAGS (if SEVERITIES includes '"tagged"'). In order to
116 provide the other arguments interactively, the commands must be
117 called with a prefix, like 'C-u M-x debbugs-gnu'. In the
118 minibuffer, lists must be entered comma-separated.
120 Default values for interactive use could be configured in the
121 customer options 'debbugs-gnu-default-severities' and
122 'debbugs-gnu-default-packages'.
124 When the result would exceed more than 500 bugs, the user is
125 asked how many bugs to retrieve at once. This value can be
126 configured in the customer option
127 'debbugs-gnu-default-hits-per-page'. However, it is not
128 recommended to exceeds the default value.
130 *note Layout:: for the presentation of the results.
132 -- Command: debbugs-gnu-bugs &rest bugs
133 -- Command: debbugs-org-bugs &rest bugs
135 The commands 'debbugs-gnu-bugs' and 'debbugs-org-bugs' show bugs
136 specified by their bug number. Interactively, the bug numbers
137 must be entered as comma-separated list.
139 *note Layout:: for the presentation of the results.
142 File: debbugs-ug.info, Node: Searching Bugs, Next: Layout, Prev: Retrieving Bugs, Up: Top
144 2 Searching in the Debbugs Database.
145 ************************************
147 The GNU Debbugs server allows full text search in the database. It
148 uses a HyperEstraier based search engine
149 (http://fallabs.com/hyperestraier/uguide-en.html#searchcond)(1).
151 -- Command: debbugs-gnu-search
152 -- Command: debbugs-org-search
154 These both commands are completely interactive. They ask for a
155 '"search phrase"' for the full text search. It is just a string
156 which contains the words to be searched for, combined by
157 operators like AND, ANDNOT and OR. If there is no operator
158 between the words, AND is used by default.
160 Wild card searches are also supported. It can be used for
161 forward match search and backward match search. For example,
162 "[BW] euro" matches words which begin with "euro". "[EW] shere"
163 matches words which end with "sphere". Moreover, regular
164 expressions are also supported. For example, "[RX] ^inter.*al$"
165 matches words which begin with "inter" and end with "al".(2)
167 While the words to be searched for are case insensitive, the
168 operators must be specified case sensitive.
170 While the search for the phrase is performed only in the bodies
171 of the messages belonging to a bug report, it is also possible to
172 discriminate the search to further bug attributes. The commands
173 ask for such key-value pairs, until an empty key is returned.
174 Possible attributes are
177 A comma-separated list of bug severities, *Note Retrieving
181 A comma-separated list of defined software packages on the
182 GNU Debbugs server, *Note Retrieving Bugs::.
185 A comma-separated list of defined user tags.
188 The address of the bug submitter.
191 A time period the bug has been in which the bug has been
192 submitted or modified.
195 Word(s) the subject of the bug report contains.
198 The status of the bug report. Valid values are "done",
199 "forwarded" and "open".
201 It is also possible to apply these commands with an empty search
202 phrase. In this case, the GNU Debbugs server is searched only
203 for bugs which fulfill the given attributes. The attributes to
204 be applied are the same as already described, plus
207 Whether archived bugs shall be searched (no value to be
211 Bugs which belong to a given source, if that attribute has
215 An arbitrary string the bug is annotated with. Usually,
216 this is the same as the status mentioned above.
221 The email address of the bug's owner, maintainer, or
222 correspondent (somebody who has participated in bug
229 The date of the last update, or the date of the bug report /
233 The date the bug has been unarchived, if ever.
236 The email address of the worker who has closed the bug (if
240 A URL or an email address.
243 The message id of the initial bug report.
246 The summary of the bug report.
248 Not all of these attributes could be queried on the GNU Debbugs
249 server via the Debbugs/SOAP backend. In this case, the results
250 of a query are discriminated on the client side, which is
251 indicated by the string "(client-side filter)" in the minibuffer
252 after the attribute name.
254 ---------- Footnotes ----------
256 (1) This has been added to the Debbugs/SOAP backend of the GNU
259 (2) Simplified forms, as described in the Hyperestraier User Guide,
263 File: debbugs-ug.info, Node: Layout, Next: Minor Mode, Prev: Searching Bugs, Up: Top
268 The commands described in the previous chapters generate (a) report
269 buffer(s) applicable for navigation. 'debbugs-gnu-*' return a
270 tabulated list, and 'debbugs-org-*' return a list of TODO items in
275 * Tabulated Lists:: Tabulated Lists.
276 * TODO Items:: TODO Items.
277 * Control Messages:: Control Messages.
280 File: debbugs-ug.info, Node: Tabulated Lists, Next: TODO Items, Up: Layout
285 A tabulated list of bug reports consist of four columns for every bug
286 entry: 'Id' (the bug number), 'State' (some bug attributes),
287 'Submitter' (the name of the bug submitter), and 'Title' (the bug
288 subject). Per default the bugs are sorted by 'Id'; this could be
289 changed by clicking in the headline.
291 Per bug retrieval only up to 500
292 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
293 in a buffer. If there shall be presented more bugs, widgets are
294 placed on the top and bottom of the buffer for navigation to further
297 Different foreground colours present further information on the bug
298 report. If the bug number uses a red colour ('debbugs-gnu-tagged'),
299 the bug has been tagged locally. The same face is used to mark bugs
300 in the submitter or title column, when the bug has been reported / is
301 maintained by the user.
303 The bug state could appear in different colours: red
304 ('debbugs-gnu-new', nobody has answered yet to this bug), ForestGreen
305 ('debbugs-gnu-handled', the bug has been modified recently),
306 MidnightBlue ('debbugs-gnu-pending', the bug is pending), orange
307 ('debbugs-gnu-stale', the bug has not been touched for a while), and
308 DarkGrey ('debbugs-gnu-done', the bug is closed). Archived bugs are
309 shown with inverse face ('debbugs-gnu-archived').
311 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
312 This enables the following key strokes:
314 '<RET>' 'debbugs-gnu-select-report'
315 '<mouse-1>' Show the email messages that discuss the bug.
318 'd' 'debbugs-gnu-display-status'
319 Show all bug attributes.
321 '/' 'debbugs-gnu-narrow-to-status'
322 Narrow the list of bugs to the bugs that match the
323 given regex in 'State', 'Submitter' or 'Title'.
325 'R' 'debbugs-gnu-show-all-blocking-reports'
326 Narrow the list of bug reports to the ones that are
327 blocking the current release.
329 'w' 'debbugs-gnu-widen'
330 Restore the full list again after narrowing.
332 'g' 'debbugs-gnu-rescan'
333 Reload all bugs from the GNU Debbugs server.
335 'B' 'debbugs-gnu-show-blocking-reports'
336 'b' 'debbugs-gnu-show-blocked-by-reports'
337 Show all bug reports which are blocking / blocked by
340 's' 'debbugs-gnu-toggle-sort'
341 Toggle sorting order of bugs.
343 't' 'debbugs-gnu-toggle-tag'
344 Toggle local tag of bugs.
346 'x' 'debbugs-gnu-toggle-suppress'
347 Toggle showing of closed bugs.
349 'C' 'debbugs-gnu-send-control-message'
350 Send a control message for this bug,
351 *note Control Messages::.
354 The user option 'debbugs-gnu-mail-backend' controls the
355 presentation of email messages produced by typing '<RET>' or by
356 clicking the mouse on a bug: if its value is 'gnus', the default, a
357 GNUS ephemeral group for that bug will be shown; if its value is
358 'rmail', the command will present an Rmail folder instead.
361 File: debbugs-ug.info, Node: TODO Items, Next: Control Messages, Prev: Tabulated Lists, Up: Layout
366 TODO items are offered as usual in 'org-mode'. The bug attributes are
367 mapped onto properties of these items. They can be shown by the usual
368 navigation in 'org-mode'.
370 Per bug retrieval only up to 500
371 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
372 in a buffer. At the end of the buffer there is a link, which allows
373 to append the next 500 bugs to the list.
375 Bug severities are mapped onto org severities, see
376 'debbugs-org-severity-priority'.
378 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
379 This enables the following key strokes:
382 Outline the bug report attributes in 'org-mode'.
384 'C-c # d' 'debbugs-gnu-display-status'
385 Show all bug attributes.
387 'C-c # t' 'debbugs-gnu-toggle-tag'
388 Toggle local tag of bugs.
390 'C-c # C' 'debbugs-gnu-send-control-message'
391 Send a control message for this bug, *note Control Messages::.
394 When the bug attributes are shown by 'org-cycle', there is a link
395 'Messages' which opens a GNUS ephemeral group for that bug.
398 File: debbugs-ug.info, Node: Control Messages, Prev: TODO Items, Up: Layout
403 Debbugs control messages are sent by email to the GNU Debbugs control
404 server. Their format is described in
405 <http://debbugs.gnu.org/server-control.html>.
407 A control message can be initiated in the tabulated list of bugs,
408 in the list of org TODO items, or in the GNUS ephemeral group or Rmail
409 folder opened for the messages belonging to a given bug. Control
410 messages can be sent to unarchived bugs only, in case a bug is
411 archived the control message 'unarchive' must be sent first.
413 In the minibuffer, the following control messages can be requested
414 (assuming that 12345 is the bug the control message is intended for).
415 The strings show the exact format of the control messages.
419 "block|unblock 12345 by 54321"
421 The second bug number is read interactively. It could be also a
422 list of comma-separated bug numbers.
427 The second argument, the Emacs version, is read interactively.
439 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
441 "tags 12345 patch|pending|security|unreproducible|wontfix"
447 "tags 12345 fixed|notabug|unreproducible|wontfix"
450 The second argument in the close message, the Emacs version, is
455 "forcemerge|merge 12345 54321"
457 The second bug number is read interactively.
464 "severity 12345 important|minor|normal|serious|wishlist"
478 "reassign 12345 PACKAGE"
480 The package name on the GNU Debbugs server is read interactively.
495 The username, read interactively, is either a package name or an
496 email address. The tag to be set is also read interactively.
499 File: debbugs-ug.info, Node: Minor Mode, Next: Command Index, Prev: Layout, Up: Top
504 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
505 like 'ChangeLog', or in commentary sections of other files. The
506 reference to such bugs have a specialized format, <Bug#12345>. The
507 hyperlinks are implemented as minor modes 'bug-reference-mode' and
508 'bug-reference-prog-mode'.
510 This package adds a new minor mode 'debbugs-browse-mode' on top of
511 them. Instead of using the default built-in Emacs browser for a given
512 bug reference, it opens a corresponding bug report buffer. The
513 customer option 'debbugs-browse-function' controls, whether
514 'debbugs-gnu-bugs' or 'debbugs-org-bugs' is called.
516 This minor mode is applicable for all URLs, not only bug
517 references. Any URL with the format <http://debbugs.gnu.org/12345>
518 will be shown in a bug report buffer, when 'debbugs-browse-mode' is
522 File: debbugs-ug.info, Node: Command Index, Next: Variable Index, Prev: Minor Mode, Up: Top