1 This is debbugs.info, produced by makeinfo version 6.0 from
4 Copyright (C) 2011-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: (debbugs). A library for communication with Debbugs.
28 File: debbugs.info, Node: Top, Next: Installation, Up: (dir)
30 Debbugs Programmer's Manual
31 ***************************
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 The Debbugs/SOAP service provides the means for developers to write
44 client applications that can send the queries with certain search
45 criteria to the Debbugs server and retrieve a set of bug reports that
46 match them. The developer may also ask the Debbugs server for
47 additional information about every bug report (e.g. subject, date,
48 originator, tags and etc.) and get all comments and attachments.
50 'debbugs', described in this document, is the Emacs library that
51 exposes to developers the available functions provided by the Debbugs
52 server. 'debbugs' uses Emacs' SOAP client library for communication
53 with the Debbugs server. In tandem with Emacs' email facilities,
54 'debbugs' provides a solution for building applications that interact
55 with the Debbugs BTS directly from Emacs without addressing Debbugs'
58 The user interface for accessing the Debbugs server for GNU
59 projects is described in *note Debbugs User Guide: (debbugs-ug)Top.
63 * Installation:: Getting and installing 'debbugs'.
64 * Configuration:: Configuring 'debbugs'.
65 * Requesting bug numbers:: How to request bug report numbers.
66 * Requesting bugs statuses:: How to request the status of bug reports.
67 * Requesting messages:: How to get messages from bug reports.
68 * Requesting user tags:: How to request tags set by users.
71 File: debbugs.info, Node: Installation, Next: Configuration, Prev: Top, Up: Top
76 Installation on Emacs 24 or later
77 ---------------------------------
79 Install 'debbugs' from the *note ELPA repository: (elisp)Packaging.
81 Installation on Emacs 22 and Emacs 23
82 -------------------------------------
84 If you want to install 'debbugs' on Emacs 22/23, you will need to
85 install the 'soap-client' library first. It can be downloaded from
86 the Emacs SOAP client project page
87 (http://code.google.com/p/emacs-soap-client/).
89 Compile the library and add it into your 'load-path':
91 (add-to-list 'load-path "/path/to/emacs-soap-client/")
93 'debbugs' library can be downloaded from the ELPA repository
94 (http://elpa.gnu.org/packages/). Compile it and set the 'load-path':
96 (add-to-list 'load-path "/path/to/debbugs/")
98 Installation on Emacs 21
99 ------------------------
101 We have not tried yet to install 'debbugs' on Emacs 21. We would
102 definitely say that the installation will require even more additional
103 libraries than needed for installation on Emacs 22/23.
106 File: debbugs.info, Node: Configuration, Next: Requesting bug numbers, Prev: Installation, Up: Top
111 'debbugs' is already configured to work with two main ports of Debbugs
112 BTS: <http://bugs.debian.org> and <http://debbugs.gnu.org>. So if you
113 intend to use one of these ports, you don't need to configure
114 'debbugs'. If you want to interact with a Debbugs port other than
115 those listed, you have to configure 'debbugs' by adding a new server
116 specifier to the 'debbugs-servers' variable. The actual port can be
117 selected by the 'debbugs-port' variable.
119 -- Variable: debbugs-servers
120 List of Debbugs server specifiers. Each entry is a list that
121 contains a string identifying the port name and the server
122 parameters in keyword-value form. The list initially contains
123 two predefined and configured Debbugs servers: '"gnu.org"' and
129 Location of WSDL. The value is a string with the URL that
130 should return the WSDL specification of the Debbugs/SOAP
131 service. This keyword is intended for future use, it is
135 The URL of the server script ('bugreport.cgi' in the default
136 Debbugs installation) that provides the access to mboxes
137 with messages from bug reports.
139 Example. Add a new Debbugs port with name "foobars.net":
144 :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
145 :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
147 -- Variable: debbugs-port
148 This variable holds the name of the currently used port. The
149 value of the variable corresponds to the Debbugs server to be
150 accessed, either '"gnu.org"' or '"debian.org"', or a user defined
153 -- Variable: debbugs-cache-expiry
154 The function 'debbugs-get-status' (*note Requesting bugs
155 statuses::) caches retrieved status entries in order to improve
156 the performance. This variable determines the number of seconds
157 an entry is cached, before it is retrieved again. A value of
158 'nil' disables cache expiration, and a value of 't' disables
159 caching. Both values are not recommended for a usual workflow.
162 File: debbugs.info, Node: Requesting bug numbers, Next: Requesting bugs statuses, Prev: Configuration, Up: Top
164 3 Requesting bug numbers
165 ************************
167 In Debbugs BTS, the bug number is the unique identifier of a bug
168 report. The functions described in this section return from the
169 Debbugs server the list of bug numbers that match a user's query.
171 -- Function: debbugs-get-bugs &rest query
172 This function returns a list of bug numbers that match the QUERY.
173 QUERY is a sequence of keyword-value pairs where the values are
174 strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
176 The keyword-value pair is a subquery. The keywords are allowed
177 to have multiple occurrence within the query at any place. The
178 subqueries with the same keyword form the logical subquery, which
179 returns the union of bugs of every subquery it contains.
181 The result of the QUERY is an intersection of results of all
187 The value is the name of the package a bug belongs to, like
188 '"emacs"', '"coreutils"', '"gnus"', or '"tramp"'.
191 This is used to retrieve bugs that belong to source with
195 This is the severity of the bug. The exact set of available
196 severities depends on the policy of a particular Debbugs
199 Debian port: '"critical"', '"grave"', '"serious"',
200 '"important"', '"normal"', '"minor"', '"wishlist"', and
203 GNU port: '"serious"', '"important"', '"normal"', '"minor"',
207 An arbitrary string the bug is annotated with. Usually,
208 this is used to mark the status of the bug. The list of
209 possible tags depends on the Debbugs port.
211 Debian port: '"patch"', '"wontfix"', '"moreinfo"',
212 '"unreproducible"', '"fixed"', '"potato"', '"woody"',
213 '"sid"', '"help"', '"security"', '"upstream"', '"pending"',
214 '"sarge"', '"sarge-ignore"', '"experimental"', '"d-i"',
215 '"confirmed"', '"ipv6"', '"lfs"', '"fixed-in-experimental"',
216 '"fixed-upstream"', '"l10n"', '"etch"', '"etch-ignore"',
217 '"lenny"', '"lenny-ignore"', '"squeeze"',
218 '"squeeze-ignore"', '"wheezy"', '"wheezy-ignore"'. The
219 actual list of tags can be found on
220 <http://www.debian.org/Bugs/Developer#tags>.
222 GNU port: '"fixed"', '"notabug"', '"wontfix"',
223 '"unreproducible"', '"moreinfo"', '"patch"', '"pending"',
224 '"help"', '"security"', '"confirmed"'. See
225 <http://debbugs.gnu.org/Developer.html#tags> for the actual
229 This is used to identify bugs by the owner's email address.
230 The special email address '"me"' is used as pattern,
231 replaced with the variable 'user-mail-address' (*note
232 (elisp)User Identification::).
235 With this keyword it is possible to filter bugs by the
236 submitter's email address. The special email address '"me"'
237 is used as pattern, replaced with the variable
241 This is used to find bugs of the packages which are
242 maintained by the person with the given email address. The
243 special email address '"me"' is used as pattern, replaced
244 with 'user-mail-address'.
247 This allows to find bug reports where the person with the
248 given email address has participated. The special email
249 address '"me"' is used as pattern, replaced with
253 With this keyword it is possible to find bugs which affect
254 the package with the given name. The bugs are chosen by the
255 value of field 'affects' in bug's status. The returned bugs
256 do not necessary belong to this package.
259 Status of bug. Valid values are '"done"', '"forwarded"' and
263 A keyword to filter for bugs which are already archived, or
264 not. Valid values are '"0"' (not archived), '"1"'
265 (archived) or '"both"'. If this keyword is not given in the
266 query, ':archive "0"' is assumed by default.
268 Example. Get all opened and forwarded release critical bugs for
269 the packages which are maintained by '"me"' and which have a
272 (let ((debbugs-port "debian.org"))
273 (debbugs-get-bugs :maint "me" :tag "patch"
278 :severity "serious"))
280 -- Function: debbugs-newest-bugs amount
281 This function returns a list of bug numbers, according to AMOUNT
282 (a number) of latest bugs.
284 Example. Get the latest six bug report numbers from Debian BTS:
286 (let ((debbugs-port "debian.org"))
287 (debbugs-newest-bugs 6))
288 => (633152 633153 633154 633155 633156 633157)
291 File: debbugs.info, Node: Requesting bugs statuses, Next: Requesting messages, Prev: Requesting bug numbers, Up: Top
293 4 Requesting bugs statuses
294 **************************
296 Bug status is a collection of fields that holds the information about
297 the state and importance of the bug report, about originator, owner
298 and various aspects of relationship with other bug reports.
300 -- Function: debbugs-get-status &rest bug-numbers
301 Return a list of status entries for the bug reports identified by
302 BUG-NUMBERS. Every returned entry is an association list with
303 the following attributes:
310 A list of package names the bug belongs to.
313 The severity of the bug report. Possible values are the
314 same as for ':severity' in 'debbugs-get-bugs' (*note
315 Requesting bug numbers::).
318 The status of the bug report, a list of strings. Possible
319 values are the same as for ':tags' in 'debbugs-get-bugs'
320 (*note Requesting bug numbers::).
323 The string '"pending"', '"forwarded"' or '"done"'.
326 Subject/Title of the bugreport.
329 The E-mail address of the bug report submitter.
332 A list of bug numbers this bug was merged with.
335 Source package name of the bug report.
338 Date of bug creation. Encoded as UNIX time.
342 Date of last update. Encoded as UNIX time.
346 Date of bug report / bug fix (empty for now). Encoded as
350 The E-mail address of the worker who has closed the bug (if
354 't' if the bug is archived, 'nil' otherwise.
357 The date the bug has been unarchived, if ever. Encoded as
362 List of version strings.
365 A URL or an E-mail address.
368 A list of bug numbers this bug blocks.
371 A list of bug numbers this bug is blocked by.
374 The message id of the initial bug report.
377 Who is responsible for fixing.
380 Always the string '"db-h"' or '"archive"'.
383 A list of package names.
388 Example. Get the status of bug number #10 from GNU BTS:
390 (let ((debbugs-port "gnu.org"))
391 (debbugs-get-status 10))
393 (((source . "unknown") (found_versions) (done) (blocks)
394 (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
395 (found) (unarchived) (blockedby) (keywords) (summary)
396 (msgid . "<87zltuz7eh.fsf@freemail.hu>") (id . 10)
397 (forwarded) (severity . "wishlist")
398 (owner . "Magnus Henoch <*****@freemail.hu>")
399 (log_modified . 1310061242.0) (location . "db-h")
400 (subject . "url-gw should support HTTP CONNECT proxies")
401 (originator . "Magnus Henoch <*****@freemail.hu>")
402 (last_modified . 1310061242.0) (pending . "pending") (affects)
403 (archived) (tags) (fixed_date) (package "emacs") (found_date)
406 -- Function: debbugs-get-attribute bug-or-message attribute
407 General accessor that returns the value of key ATTRIBUTE.
408 BUG-OR-MESSAGE must be a list element returned by either
409 'debbugs-get-status' or 'debbugs-get-bug-log' (*note Requesting
412 Example. Return the originator of the last submitted bug report:
414 (let ((debbags-port "gnu.org"))
415 (debbugs-get-attribute
416 (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
418 => "Jack Daniels <jack@daniels.com>"
421 File: debbugs.info, Node: Requesting messages, Next: Requesting user tags, Prev: Requesting bugs statuses, Up: Top
423 5 Requesting messages
424 *********************
426 -- Function: debbugs-get-bug-log bug-number
427 Returns a list of messages related to BUG-NUMBER. Every message
428 is an association list with the following attributes:
431 The number of the message inside the bug log. The numbers
432 are ascending, newer messages have a higher number.
434 The header lines from the E-mail messages, as arrived at the
439 A list of possible attachments, or 'nil'. Not implemented
442 -- Function: debbugs-get-message-numbers messages
443 Returns the message numbers of MESSAGES. MESSAGES must be the
444 result of a 'debbugs-get-bug-log' call.
446 Example. Get message numbers from bug report #456789 log from
449 (let ((debbugs-port "debian.org"))
450 (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
453 -- Function: debbugs-get-message messages message-number
454 Returns the message MESSAGE-NUMBER of MESSAGES. MESSAGES must be
455 the result of a 'debbugs-get-bug-log' call. The returned message
456 is a list of strings. The first element are the header lines of
457 the message, the second element is the body of the message.
458 Further elements of the list, if any, are attachments of the
459 message. If there is no message with MESSAGE-NUMBER, the
460 function returns 'nil'.
462 Example: Return the first message of the last submitted bug
465 (let* ((debbugs-port "gnu.org")
466 (messages (apply 'debbugs-get-bug-log
467 (debbugs-newest-bugs 1))))
470 (car (debbugs-get-message-numbers messages))))
472 -- Function: debbugs-get-mbox bug-number mbox-type &optional filename
473 Download mbox with all messages from bug report BUG-NUMBER.
474 MBOX-TYPE specifies a type of mbox and can be one of the
478 Download mbox folder, i.e. mbox with messages as they
479 arrived at the Debbugs server.
482 Download maintainer's mbox, i.e. mbox with messages as they
483 are resent from the Debbugs server.
487 Download status mbox. The use of either symbol depends on
488 the actual Debbugs server configuration. For '"gnu.org"',
489 use the former; for '"debian.org' - the latter.
491 FILENAME, if non-'nil', is the name of the file to store mbox.
492 If FILENAME is 'nil', the downloaded mbox is inserted into the
495 Note, that mbox downloading will work only if the
496 ':bugreport-url' field of the 'debbugs-servers' variable is
497 specified (*note Configuration::).
500 File: debbugs.info, Node: Requesting user tags, Prev: Requesting messages, Up: Top
502 6 Requesting user tags
503 **********************
505 A user tag is a string, a user has assigned to one or several bugs.
506 The user is identified by an email address. The port '"gnu.org"' uses
507 also package names as user identification.
509 -- Function: debbugs-get-usertag &rest query
510 Return a list of bug numbers which match QUERY.
512 QUERY is a sequence of keyword-value pairs where the values are
513 strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
518 The value is the name of the package a bug belongs to, like
519 '"emacs"', '"coreutils"', or '"tramp"'. It can also be an
520 email address of a user who has applied a user tag. The
521 special email address '"me"' is used as pattern, replaced
522 with 'user-mail-address'. There must be at least one such
523 entry; it is recommended to have exactly one.
526 A string applied as user tag. Often, it is a subproduct
527 identification, like '"cedet"' or '"tramp"' for the package
530 If there is no ':tag' entry, no bug numbers will be returned but
531 a list of existing user tags for ':user'.
533 Example. Get all user tags for the package '"emacs"':
535 (let ((debbugs-port "gnu.org"))
536 (debbugs-get-usertag :user "emacs"))
537 => ("www" "solaris" "ls-lisp" "cygwin")
539 Get all bugs tagged by package '"emacs"' with '"www"' or
542 (let ((debbugs-port "gnu.org"))
543 (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
550 Node: Installation
\7f3179
551 Node: Configuration
\7f4278
552 Node: Requesting bug numbers
\7f6629
553 Node: Requesting bugs statuses
\7f11883
554 Node: Requesting messages
\7f15934
555 Node: Requesting user tags
\7f18949