1 This is debbugs-ug.info, produced by makeinfo version 5.0 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).
304 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
305 This enables the following key strokes:
307 '<RET>' 'debbugs-gnu-select-report'
308 '<mouse-1>' Open a GNUS ephemeral group for that bug.
311 'd' 'debbugs-gnu-display-status'
312 Show all bug attributes.
314 'g' 'debbugs-gnu-rescan'
315 Reload all bugs from the GNU Debbugs server.
317 'B' 'debbugs-gnu-show-blocking-reports'
318 'b' 'debbugs-gnu-show-blocked-by-reports'
319 Show all bug reports which are blocking / blocked by this bug.
321 's' 'debbugs-gnu-toggle-sort'
322 Toggle sorting order of bugs.
324 't' 'debbugs-gnu-toggle-tag'
325 Toggle local tag of bugs.
327 'x' 'debbugs-gnu-toggle-suppress'
328 Toggle showing of closed bugs.
330 'C' 'debbugs-gnu-send-control-message'
331 Send a control message for this bug, *note Control Messages::.
335 File: debbugs-ug.info, Node: TODO Items, Next: Control Messages, Prev: Tabulated Lists, Up: Layout
340 TODO items are offered as usual in 'org-mode'. The bug attributes are
341 mapped onto properties of these items. They can be shown by the usual
342 navigation in 'org-mode'.
344 Per bug retrieval only up to 500
345 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
346 in a buffer. At the end of the buffer there is a link, which allows to
347 append the next 500 bugs to the list.
349 Bug severities are mapped onto org severities, see
350 'debbugs-org-severity-priority'.
352 The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
353 This enables the following key strokes:
356 Outline the bug report attributes in 'org-mode'.
358 'C-c # d' 'debbugs-gnu-display-status'
359 Show all bug attributes.
361 'C-c # t' 'debbugs-gnu-toggle-tag'
362 Toggle local tag of bugs.
364 'C-c # C' 'debbugs-gnu-send-control-message'
365 Send a control message for this bug, *note Control Messages::.
368 When the bug attributes are shown by 'org-cycle', there is a link
369 'Messages' which opens a GNUS ephemeral group for that bug.
372 File: debbugs-ug.info, Node: Control Messages, Prev: TODO Items, Up: Layout
377 Debbugs control messages are sent by email to the GNU Debbugs control
378 server. Their format is described in
379 <http://debbugs.gnu.org/server-control.html>.
381 A control message can be initiated in the tabulated list of bugs, in
382 the list of org TODO items, or in the GNUS ephemeral group opened for
383 the messages belonging to a given bug. In the minibuffer, the following
384 control messages can be requested (assuming that 12345 is the bug the
385 control message is intended for). The strings show the exact format of
386 the control messages.
390 "block|unblock 12345 by 54321"
392 The second bug number is read interactively. It could be also a
393 list of comma-separated bug numbers.
398 The second argument, the Emacs version, is read interactively.
410 "tags 12345 confirmed|fixed|help|moreinfo|notabug"
412 "tags 12345 patch|pending|security|unreproducible|wontfix"
418 "tags 12345 fixed|notabug|unreproducible|wontfix"
421 The second argument in the close message, the Emacs version, is
426 "forcemerge|merge 12345 54321"
428 The second bug number is read interactively.
435 "severity 12345 important|minor|normal|serious|wishlist"
449 "reassign 12345 PACKAGE"
451 The package name on the GNU Debbugs server is read interactively.
466 The username, read interactively, is either a package name or an
467 email address. The tag to be set is also read interactively.
470 File: debbugs-ug.info, Node: Minor Mode, Next: Command Index, Prev: Layout, Up: Top
475 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
476 like 'ChangeLog', or in commentary sections of other files. The
477 reference to such bugs have a specialized format, <Bug#12345>. The
478 hyperlinks are implemented as minor modes 'bug-reference-mode' and
479 'bug-reference-prog-mode'.
481 This package adds a new minor mode 'debbugs-browse-mode' on top of
482 them. Instead of using the default built-in Emacs browser for a given
483 bug reference, it opens a corresponding bug report buffer. The customer
484 option 'debbugs-browse-function' controls, whether 'debbugs-gnu-bugs' or
485 'debbugs-org-bugs' is called.
487 This minor mode is applicable for all URLs, not only bug references.
488 Any URL with the format <http://debbugs.gnu.org/12345> will be shown in
489 a bug report buffer, when 'debbugs-browse-mode' is enabled.
492 File: debbugs-ug.info, Node: Command Index, Next: Variable Index, Prev: Minor Mode, Up: Top