1 This is debbugs-ug.info, produced by makeinfo version 5.2 from
4 Copyright (C) 2015 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 section
11 entitled "GNU Free Documentation License" in the Emacs manual.
13 This document is part of a collection distributed under the GNU
14 Free Documentation License. If you want to distribute this
15 document separately from the collection, you can do so by adding a
16 copy of the license to the document, as described in section 6 of
19 All Emacs Lisp code contained in this document may be used,
20 distributed, and modified without restriction.
21 INFO-DIR-SECTION Emacs
23 * Debbugs UG: (debbugs-ug). Debbugs User Interface in Emacs.
27 File: debbugs-ug.info, Node: Top, Next: Retrieving Bugs, Up: (dir)
32 Debbugs is a bugtracking system (BTS) that was initially written for the
33 Debian project but currently used also by the GNU project. The main
34 distinctive feature of Debbugs is that it's mostly email-based. All
35 actions on bug reports: opening, closing, changing the status,
36 commenting, forwarding are performed via email by sending specially
37 composed letters to the particular mail addresses. However, searching
38 the bug reports, querying bug report status and viewing comments have
39 been web-based for a long time. To overcome this inconvenience the
40 Debbugs/SOAP service was introduced.
42 Based on the Debbugs/SOAP service, frontends are written which offer
43 handling of bugs inside Emacs. These frontends are restricted to the
44 GNU Debbugs server. Bugs are presented either as tabulated list
45 ('debbugs-gnu') or as 'org-mode' TODO list ('debbugs-org', *note Org
46 Mode: (org)Top.). As backend they use the 'debbugs' Emacs library
47 (*note Debbugs Programmer's Manual: (debbugs)Top.).
51 * Retrieving Bugs:: How to retrieve bugs.
52 * Searching Bugs:: How to search in the debbugs database.
53 * Layout:: How the results are presented.
54 * Minor Mode:: How to use browse bug URLs.
56 * Command Index:: Debbugs commands.
57 * Variable Index:: User options and variables.
58 * Key Index:: Keyboard strokes on bug report buffers.
61 File: debbugs-ug.info, Node: Retrieving Bugs, Next: Searching Bugs, Prev: Top, Up: Top
66 Bugs are retrieved by the 'debbugs-gnu' or 'debbugs-org' commands. In
67 their simple version, they retrieve just bugs for the '"emacs"' package
68 on the GNU Debbugs server, filtered by bug severities. Further
69 filtering is possible when the commands are called with a prefix.
71 When the bug numbers to be retrieved are known, the commands
72 'debbugs-gnu-bugs' or 'debbugs-org-bugs' are applicable.
74 -- Command: debbugs-gnu severities &optional packages archivedp
76 -- Command: debbugs-org severities &optional packages archivedp
79 These commands retrieve bug reports from the GNU Debbugs server.
80 'debbugs-gnu' returns a tabulated list, and 'debbugs-org' returns a
81 list of TODO items in 'org-mode'. If there were more than
82 'debbugs-gnu-default-hits-per-page' bug results from the query,
83 there are widgets ('debbugs-gnu') or links ('debbugs-org') in the
84 result buffer for retrieving the other results.
86 SEVERITIES is a list of strings which filter for the severities of
87 the bugs to be retrieved. Valid severities are '"serious"',
88 '"important"', '"normal"', '"minor"' and '"wishlist"' (see also the
89 constant 'debbugs-gnu-all-severities'). If the list is empty,
90 there is no filtering with respect to severities. The keyword
91 '"tagged"', which is also possible, is not a severity in the GNU
92 Debbugs server but allows to restrict the result to bugs with a
95 PACKAGES, also a list of strings, point to the defined software
96 packages on the GNU Debbugs server which shall be taken into
97 account. The existing package names are compiled into the constant
98 'debbugs-gnu-all-packages'.
100 ARCHIVEDP, if non-'nil', extends the result also on archived bugs
101 on the GNU Debbugs server.
103 SUPPRESS shall also distinct between 'nil' and non-'nil'. When
104 non-'nil', closed bugs are suppressed from the results.
106 When SEVERITIES contains the severity '"tagged"', TAGS is consulted
107 in order to restrict the result on bugs which are tagged with one
108 of the strings of the list TAGS. This list can also be empty; in
109 this case locally tagged bugs are included into the results.
111 Called interactively, the commands require just the SEVERITIES and
112 the TAGS (if SEVERITIES includes '"tagged"'). In order to provide
113 the other arguments interactively, the commands must be called with
114 a prefix, like 'C-u M-x debbugs-gnu'. In the minibuffer, lists
115 must be entered comma-separated.
117 Default values for interactive use could be configured in the
118 customer options 'debbugs-gnu-default-severities' and
119 'debbugs-gnu-default-packages'.
121 When the result would exceed more than 500 bugs, the user is asked
122 how many bugs to retrieve at once. This value can be configured in
123 the customer option 'debbugs-gnu-default-hits-per-page'. However,
124 it is not recommended to exceeds the default value.
126 *note Layout:: for the presentation of the results.
128 -- Command: debbugs-gnu-bugs &rest bugs
129 -- Command: debbugs-org-bugs &rest bugs
131 The commands 'debbugs-gnu-bugs' and 'debbugs-org-bugs' show bugs
132 specified by their bug number. Interactively, the bug numbers must
133 be entered as comma-separated list.
135 *note Layout:: for the presentation of the results.
138 File: debbugs-ug.info, Node: Searching Bugs, Next: Layout, Prev: Retrieving Bugs, Up: Top
140 2 Searching in the Debbugs Database.
141 ************************************
143 The GNU Debbugs server allows full text search in the database. It uses
144 a HyperEstraier based search engine
145 (http://fallabs.com/hyperestraier/uguide-en.html#searchcond)(1).
147 -- Command: debbugs-gnu-search
148 -- Command: debbugs-org-search
150 These both commands are completely interactive. They ask for a
151 '"search phrase"' for the full text search. It is just a string
152 which contains the words to be searched for, combined by operators
153 like AND, ANDNOT and OR. If there is no operator between the words,
154 AND is used by default.
156 Wild card searches are also supported. It can be used for forward
157 match search and backward match search. For example, "[BW] euro"
158 matches words which begin with "euro". "[EW] shere" matches words
159 which end with "sphere". Moreover, regular expressions are also
160 supported. For example, "[RX] ^inter.*al$" matches words which
161 begin with "inter" and end with "al".(2)
163 While the words to be searched for are case insensitive, the
164 operators must be specified case sensitive.
166 While the search for the phrase is performed only in the bodies of
167 the messages belonging to a bug report, it is also possible to
168 discriminate the search to further bug attributes. The commands
169 ask for such key-value pairs, until an empty key is returned.
170 Possible attributes are
173 A comma-separated list of bug severities, *Note Retrieving
177 A comma-separated list of defined software packages on the GNU
178 Debbugs server, *Note Retrieving Bugs::.
181 A comma-separated list of defined user tags.
184 The address of the bug submitter.
187 A time period the bug has been in which the bug has been
188 submitted or modified.
191 Word(s) the subject of the bug report contains.
194 The status of the bug report. Valid values are "done",
195 "forwarded" and "open".
197 It is also possible to apply these commands with an empty search
198 phrase. In this case, the GNU Debbugs server is searched only for
199 bugs which fulfill the given attributes. The attributes to be
200 applied are the same as already described, plus
203 Whether archived bugs shall be searched (no value to be
207 Bugs which belong to a given source, if that attribute has
211 An arbitrary string the bug is annotated with. Usually, this
212 is the same as the status mentioned above.
217 The email address of the bug's owner, maintainer, or
218 correspondent (somebody who has participated in bug messages).
224 The date of the last update, or the date of the bug report /
228 The date the bug has been unarchived, if ever.
231 The email address of the worker who has closed the bug (if
235 A URL or an email address.
238 The message id of the initial bug report.
241 The summary of the bug report.
243 Not all of these attributes could be queried on the GNU Debbugs
244 server via the Debbugs/SOAP backend. In this case, the results of
245 a query are discriminated on the client side, which is indicated by
246 the string "(client-side filter)" in the minibuffer after the
249 ---------- Footnotes ----------
251 (1) This has been added to the Debbugs/SOAP backend of the GNU
254 (2) Simplified forms, as described in the Hyperestraier User Guide,
258 File: debbugs-ug.info, Node: Layout, Next: Minor Mode, Prev: Searching Bugs, Up: Top
263 The commands described in the previous chapters generate (a) report
264 buffer(s) applicable for navigation. 'debbugs-gnu-*' return a tabulated
265 list, and 'debbugs-org-*' return a list of TODO items in 'org-mode'.
269 * Tabulated Lists:: Tabulated Lists.
270 * TODO Items:: TODO Items.
271 * Control Messages:: Control Messages.
274 File: debbugs-ug.info, Node: Tabulated Lists, Next: TODO Items, Up: Layout
279 A tabulated list of bug reports consist of four columns for every bug
280 entry: 'Id' (the bug number), 'State' (some bug attributes), 'Submitter'
281 (the name of the bug submitter), and 'Title' (the bug subject). Per
282 default the bugs are sorted by 'Id'; this could be changed by clicking
285 Per bug retrieval only up to 500
286 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
287 in a buffer. If there shall be presented more bugs, widgets are placed
288 on the top and bottom of the buffer for navigation to further report
291 Different foreground colours present further information on the bug
292 report. If the bug number uses a red colour ('debbugs-gnu-tagged'), the
293 bug has been tagged locally. The same face is used to mark bugs in the
294 submitter or title column, when the bug has been reported / is
295 maintained by the user.
297 The bug state could appear in different colours: red
298 ('debbugs-gnu-new', nobody has answered yet to this bug), ForestGreen
299 ('debbugs-gnu-handled', the bug has been modified recently),
300 MidnightBlue ('debbugs-gnu-pending', the bug is pending), orange
301 ('debbugs-gnu-stale', the bug has not been touched for a while), and
302 DarkGrey ('debbugs-gnu-done', the bug is closed). Archived bugs are
303 shown with inverse face ('debbugs-gnu-archived').
305 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
306 This enables the following key strokes:
308 '<RET>' 'debbugs-gnu-select-report'
309 '<mouse-1>' Open a GNUS ephemeral group for that bug.
312 'd' 'debbugs-gnu-display-status'
313 Show all bug attributes.
315 'g' 'debbugs-gnu-rescan'
316 Reload all bugs from the GNU Debbugs server.
318 'B' 'debbugs-gnu-show-blocking-reports'
319 'b' 'debbugs-gnu-show-blocked-by-reports'
320 Show all bug reports which are blocking / blocked by this bug.
322 's' 'debbugs-gnu-toggle-sort'
323 Toggle sorting order of bugs.
325 't' 'debbugs-gnu-toggle-tag'
326 Toggle local tag of bugs.
328 'x' 'debbugs-gnu-toggle-suppress'
329 Toggle showing of closed bugs.
331 'C' 'debbugs-gnu-send-control-message'
332 Send a control message for this bug, *note Control Messages::.
336 File: debbugs-ug.info, Node: TODO Items, Next: Control Messages, Prev: Tabulated Lists, Up: Layout
341 TODO items are offered as usual in 'org-mode'. The bug attributes are
342 mapped onto properties of these items. They can be shown by the usual
343 navigation in 'org-mode'.
345 Per bug retrieval only up to 500
346 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
347 in a buffer. At the end of the buffer there is a link, which allows to
348 append the next 500 bugs to the list.
350 Bug severities are mapped onto org severities, see
351 'debbugs-org-severity-priority'.
353 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
354 This enables the following key strokes:
357 Outline the bug report attributes in 'org-mode'.
359 'C-c # d' 'debbugs-gnu-display-status'
360 Show all bug attributes.
362 'C-c # t' 'debbugs-gnu-toggle-tag'
363 Toggle local tag of bugs.
365 'C-c # C' 'debbugs-gnu-send-control-message'
366 Send a control message for this bug, *note Control Messages::.
369 When the bug attributes are shown by 'org-cycle', there is a link
370 'Messages' which opens a GNUS ephemeral group for that bug.
373 File: debbugs-ug.info, Node: Control Messages, Prev: TODO Items, Up: Layout
378 Debbugs control messages are sent by email to the GNU Debbugs control
379 server. Their format is described in
380 <http://debbugs.gnu.org/server-control.html>.
382 A control message can be initiated in the tabulated list of bugs, in
383 the list of org TODO items, or in the GNUS ephemeral group opened for
384 the messages belonging to a given bug. Control messages can be sent to
385 unarchived bugs only, in case a bug is archived the control message
386 'unarchive' must be sent first.
388 In the minibuffer, the following control messages can be requested
389 (assuming that 12345 is the bug the control message is intended for).
390 The strings show the exact format of the control messages.
394 "block|unblock 12345 by 54321"
396 The second bug number is read interactively. It could be also a
397 list of comma-separated bug numbers.
402 The second argument, the Emacs version, is read interactively.
414 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
416 "tags 12345 patch|pending|security|unreproducible|wontfix"
422 "tags 12345 fixed|notabug|unreproducible|wontfix"
425 The second argument in the close message, the Emacs version, is
430 "forcemerge|merge 12345 54321"
432 The second bug number is read interactively.
439 "severity 12345 important|minor|normal|serious|wishlist"
453 "reassign 12345 PACKAGE"
455 The package name on the GNU Debbugs server is read interactively.
470 The username, read interactively, is either a package name or an
471 email address. The tag to be set is also read interactively.
474 File: debbugs-ug.info, Node: Minor Mode, Next: Command Index, Prev: Layout, Up: Top
479 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
480 like 'ChangeLog', or in commentary sections of other files. The
481 reference to such bugs have a specialized format, <Bug#12345>. The
482 hyperlinks are implemented as minor modes 'bug-reference-mode' and
483 'bug-reference-prog-mode'.
485 This package adds a new minor mode 'debbugs-browse-mode' on top of
486 them. Instead of using the default built-in Emacs browser for a given
487 bug reference, it opens a corresponding bug report buffer. The customer
488 option 'debbugs-browse-function' controls, whether 'debbugs-gnu-bugs' or
489 'debbugs-org-bugs' is called.
491 This minor mode is applicable for all URLs, not only bug references.
492 Any URL with the format <http://debbugs.gnu.org/12345> will be shown in
493 a bug report buffer, when 'debbugs-browse-mode' is enabled.
496 File: debbugs-ug.info, Node: Command Index, Next: Variable Index, Prev: Minor Mode, Up: Top