1 This is debbugs.info, produced by makeinfo version 5.0 from
4 Copyright (C) 2011-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: (debbugs). A library for communication with Debbugs.
27 File: debbugs.info, Node: Top, Next: Installation, Up: (dir)
29 Debbugs Programmer's Manual
30 ***************************
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 The Debbugs/SOAP service provides the means for developers to write
43 client applications that can send the queries with certain search
44 criteria to the Debbugs server and retrieve a set of bug reports that
45 match them. The developer may also ask the Debbugs server for
46 additional information about every bug report (e.g. subject, date,
47 originator, tags and etc.) and get all comments and attachments.
49 'debbugs', described in this document, is the Emacs library that
50 exposes to developers the available functions provided by the Debbugs
51 server. 'debbugs' uses Emacs' SOAP client library for communication
52 with the Debbugs server. In tandem with Emacs' email facilities,
53 'debbugs' provides a solution for building applications that interact
54 with the Debbugs BTS directly from Emacs without addressing Debbugs' web
59 * Installation:: Getting and installing 'debbugs'.
60 * Configuration:: Configuring 'debbugs'.
61 * Requesting bug numbers:: How to request bug report numbers.
62 * Requesting bugs statuses:: How to request the status of bug reports.
63 * Requesting messages:: How to get messages from bug reports.
64 * Requesting user tags:: How to request tags set by users.
67 File: debbugs.info, Node: Installation, Next: Configuration, Prev: Top, Up: Top
72 Installation on Emacs 24 or later
73 ---------------------------------
75 Install 'debbugs' from the *note ELPA repository: (elisp)Packaging.
77 Installation on Emacs 22 and Emacs 23
78 -------------------------------------
80 If you want to install 'debbugs' on Emacs 22/23, you will need to
81 install the 'soap-client' library first. It can be downloaded from the
82 Emacs SOAP client project page
83 (http://code.google.com/p/emacs-soap-client/).
85 Compile the library and add it into your 'load-path':
87 (add-to-list 'load-path "/path/to/emacs-soap-client/")
89 'debbugs' library can be downloaded from the ELPA repository
90 (http://elpa.gnu.org/packages/). Compile it and set the 'load-path':
92 (add-to-list 'load-path "/path/to/debbugs/")
94 Installation on Emacs 21
95 ------------------------
97 We have not tried yet to install 'debbugs' on Emacs 21. We would
98 definitely say that the installation will require even more additional
99 libraries than needed for installation on Emacs 22/23.
102 File: debbugs.info, Node: Configuration, Next: Requesting bug numbers, Prev: Installation, Up: Top
107 'debbugs' is already configured to work with two main ports of Debbugs
108 BTS: <http://bugs.debian.org> and <http://debbugs.gnu.org>. So if you
109 intend to use one of these ports, you don't need to configure 'debbugs'.
110 If you want to interact with a Debbugs port other than those listed, you
111 have to configure 'debbugs' by adding a new server specifier to the
112 'debbugs-servers' variable. The actual port can be selected by the
113 'debbugs-port' variable.
115 -- Variable: debbugs-servers
116 List of Debbugs server specifiers. Each entry is a list that
117 contains a string identifying the port name and the server
118 parameters in keyword-value form. The list initially contains two
119 predefined and configured Debbugs servers: '"gnu.org"' and
125 Location of WSDL. The value is a string with the URL that
126 should return the WSDL specification of the Debbugs/SOAP
127 service. This keyword is intended for future use, it is
131 The URL of the server script ('bugreport.cgi' in the default
132 Debbugs installation) that provides the access to mboxes with
133 messages from bug reports.
135 Example. Add a new Debbugs port with name "foobars.net":
140 :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
141 :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
143 -- Variable: debbugs-port
144 This variable holds the name of the currently used port. The value
145 of the variable corresponds to the Debbugs server to be accessed,
146 either '"gnu.org"' or '"debian.org"', or a user defined port name.
149 File: debbugs.info, Node: Requesting bug numbers, Next: Requesting bugs statuses, Prev: Configuration, Up: Top
151 3 Requesting bug numbers
152 ************************
154 In Debbugs BTS, the bug number is the unique identifier of a bug report.
155 The functions described in this section return from the Debbugs server
156 the list of bug numbers that match a user's query.
158 -- Function: debbugs-get-bugs &rest query
159 This function returns a list of bug numbers that match the QUERY.
160 QUERY is a sequence of keyword-value pairs where the values are
161 strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
163 The keyword-value pair is a subquery. The keywords are allowed to
164 have multiple occurrence within the query at any place. The
165 subqueries with the same keyword form the logical subquery, which
166 returns the union of bugs of every subquery it contains.
168 The result of the QUERY is an intersection of results of all
174 The value is the name of the package a bug belongs to, like
175 '"emacs"', '"coreutils"', '"gnus"', or '"tramp"'.
178 This is used to retrieve bugs that belong to source with given
182 This is the severity of the bug. The exact set of available
183 severities depends on the policy of a particular Debbugs port:
185 Debian port: '"critical"', '"grave"', '"serious"',
186 '"important"', '"normal"', '"minor"', '"wishlist"', and
189 GNU port: '"serious"', '"important"', '"normal"', '"minor"',
193 An arbitrary string the bug is annotated with. Usually, this
194 is used to mark the status of the bug. The list of possible
195 tags depends on the Debbugs port.
197 Debian port: '"patch"', '"wontfix"', '"moreinfo"',
198 '"unreproducible"', '"fixed"', '"potato"', '"woody"', '"sid"',
199 '"help"', '"security"', '"upstream"', '"pending"', '"sarge"',
200 '"sarge-ignore"', '"experimental"', '"d-i"', '"confirmed"',
201 '"ipv6"', '"lfs"', '"fixed-in-experimental"',
202 '"fixed-upstream"', '"l10n"', '"etch"', '"etch-ignore"',
203 '"lenny"', '"lenny-ignore"', '"squeeze"', '"squeeze-ignore"',
204 '"wheezy"', '"wheezy-ignore"'. The actual list of tags can be
205 found on <http://www.debian.org/Bugs/Developer#tags>.
207 GNU port: '"fixed"', '"notabug"', '"wontfix"',
208 '"unreproducible"', '"moreinfo"', '"patch"', '"pending"',
209 '"help"', '"security"', '"confirmed"'. See
210 <http://debbugs.gnu.org/Developer.html#tags> for the actual
214 This is used to identify bugs by the owner's email address.
215 The special email address '"me"' is used as pattern, replaced
216 with the variable 'user-mail-address' (*note (elisp)User
220 With this keyword it is possible to filter bugs by the
221 submitter's email address. The special email address '"me"'
222 is used as pattern, replaced with the variable
226 This is used to find bugs of the packages which are maintained
227 by the person with the given email address. The special email
228 address '"me"' is used as pattern, replaced with
232 This allows to find bug reports where the person with the
233 given email address has participated. The special email
234 address '"me"' is used as pattern, replaced with
238 With this keyword it is possible to find bugs which affect the
239 package with the given name. The bugs are chosen by the value
240 of field 'affects' in bug's status. The returned bugs do not
241 necessary belong to this package.
244 Status of bug. Valid values are '"done"', '"forwarded"' and
248 A keyword to filter for bugs which are already archived, or
249 not. Valid values are '"0"' (not archived), '"1"' (archived)
250 or '"both"'. If this keyword is not given in the query,
251 ':archive "0"' is assumed by default.
253 Example. Get all opened and forwarded release critical bugs for
254 the packages which are maintained by '"me"' and which have a patch:
256 (let ((debbugs-port "debian.org"))
257 (debbugs-get-bugs :maint "me" :tag "patch"
262 :severity "serious"))
264 -- Function: debbugs-newest-bugs amount
265 This function returns a list of bug numbers, according to AMOUNT (a
266 number) of latest bugs.
268 Example. Get the latest six bug report numbers from Debian BTS:
270 (let ((debbugs-port "debian.org"))
271 (debbugs-newest-bugs 6))
272 => (633152 633153 633154 633155 633156 633157)
275 File: debbugs.info, Node: Requesting bugs statuses, Next: Requesting messages, Prev: Requesting bug numbers, Up: Top
277 4 Requesting bugs statuses
278 **************************
280 Bug status is a collection of fields that holds the information about
281 the state and importance of the bug report, about originator, owner and
282 various aspects of relationship with other bug reports.
284 -- Function: debbugs-get-status &rest bug-numbers
285 Return a list of status entries for the bug reports identified by
286 BUG-NUMBERS. Every returned entry is an association list with the
287 following attributes:
294 A list of package names the bug belongs to.
297 The severity of the bug report. Possible values are the same
298 as for ':severity' in 'debbugs-get-bugs' (*note Requesting bug
302 The status of the bug report, a list of strings. Possible
303 values are the same as for ':tags' in 'debbugs-get-bugs'
304 (*note Requesting bug numbers::).
307 The string '"pending"', '"forwarded"' or '"done"'.
310 Subject/Title of the bugreport.
313 The E-mail address of the bug report submitter.
316 A list of bug numbers this bug was merged with.
319 Source package name of the bug report.
322 Date of bug creation. Encoded as UNIX time.
326 Date of last update. Encoded as UNIX time.
330 Date of bug report / bug fix (empty for now). Encoded as UNIX
334 The E-mail address of the worker who has closed the bug (if
338 't' if the bug is archived, 'nil' otherwise.
341 The date the bug has been unarchived, if ever. Encoded as
346 List of version strings.
349 A URL or an E-mail address.
352 A list of bug numbers this bug blocks.
355 A list of bug numbers this bug is blocked by.
358 The message id of the initial bug report.
361 Who is responsible for fixing.
364 Always the string '"db-h"' or '"archive"'.
367 A list of package names.
372 Example. Get the status of bug number #10 from GNU BTS:
374 (let ((debbugs-port "gnu.org"))
375 (debbugs-get-status 10))
377 (((source . "unknown") (found_versions) (done) (blocks)
378 (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
379 (found) (unarchived) (blockedby) (keywords) (summary)
380 (msgid . "<87zltuz7eh.fsf@freemail.hu>") (id . 10)
381 (forwarded) (severity . "wishlist")
382 (owner . "Magnus Henoch <*****@freemail.hu>")
383 (log_modified . 1310061242.0) (location . "db-h")
384 (subject . "url-gw should support HTTP CONNECT proxies")
385 (originator . "Magnus Henoch <*****@freemail.hu>")
386 (last_modified . 1310061242.0) (pending . "pending") (affects)
387 (archived) (tags) (fixed_date) (package "emacs") (found_date)
390 -- Function: debbugs-get-attribute bug-or-message attribute
391 General accessor that returns the value of key ATTRIBUTE.
392 BUG-OR-MESSAGE must be a list element returned by either
393 'debbugs-get-status' or 'debbugs-get-bug-log' (*note Requesting
396 Example. Return the originator of the last submitted bug report:
398 (let ((debbags-port "gnu.org"))
399 (debbugs-get-attribute
400 (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
402 => "Jack Daniels <jack@daniels.com>"
405 File: debbugs.info, Node: Requesting messages, Next: Requesting user tags, Prev: Requesting bugs statuses, Up: Top
407 5 Requesting messages
408 *********************
410 -- Function: debbugs-get-bug-log bug-number
411 Returns a list of messages related to BUG-NUMBER. Every message is
412 an association list with the following attributes:
415 The number of the message inside the bug log. The numbers are
416 ascending, newer messages have a higher number.
418 The header lines from the E-mail messages, as arrived at the
423 A list of possible attachments, or 'nil'. Not implemented yet
426 -- Function: debbugs-get-message-numbers messages
427 Returns the message numbers of MESSAGES. MESSAGES must be the
428 result of a 'debbugs-get-bug-log' call.
430 Example. Get message numbers from bug report #456789 log from
433 (let ((debbugs-port "debian.org"))
434 (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
437 -- Function: debbugs-get-message messages message-number
438 Returns the message MESSAGE-NUMBER of MESSAGES. MESSAGES must be
439 the result of a 'debbugs-get-bug-log' call. The returned message
440 is a list of strings. The first element are the header lines of
441 the message, the second element is the body of the message.
442 Further elements of the list, if any, are attachments of the
443 message. If there is no message with MESSAGE-NUMBER, the function
446 Example: Return the first message of the last submitted bug report
449 (let* ((debbugs-port "gnu.org")
450 (messages (apply 'debbugs-get-bug-log
451 (debbugs-newest-bugs 1))))
454 (car (debbugs-get-message-numbers messages))))
456 -- Function: debbugs-get-mbox bug-number mbox-type &optional filename
457 Download mbox with all messages from bug report BUG-NUMBER.
458 MBOX-TYPE specifies a type of mbox and can be one of the following
462 Download mbox folder, i.e. mbox with messages as they arrived
463 at the Debbugs server.
466 Download maintainer's mbox, i.e. mbox with messages as they
467 are resent from the Debbugs server.
471 Download status mbox. The use of either symbol depends on the
472 actual Debbugs server configuration. For '"gnu.org"', use the
473 former; for '"debian.org' - the latter.
475 FILENAME, if non-'nil', is the name of the file to store mbox. If
476 FILENAME is 'nil', the downloaded mbox is inserted into the current
479 Note, that mbox downloading will work only if the ':bugreport-url'
480 field of the 'debbugs-servers' variable is specified (*note
484 File: debbugs.info, Node: Requesting user tags, Prev: Requesting messages, Up: Top
486 6 Requesting user tags
487 **********************
489 A user tag is a string, a user has assigned to one or several bugs. The
490 user is identified by an email address. The port '"gnu.org"' uses also
491 package names as user identification.
493 -- Function: debbugs-get-usertag &rest query
494 Return a list of bug numbers which match QUERY.
496 QUERY is a sequence of keyword-value pairs where the values are
497 strings, i.e. :KEYWORD "VALUE" [:KEYWORD "VALUE"]*
502 The value is the name of the package a bug belongs to, like
503 '"emacs"', '"coreutils"', or '"tramp"'. It can also be an
504 email address of a user who has applied a user tag. The
505 special email address '"me"' is used as pattern, replaced with
506 'user-mail-address'. There must be at least one such entry;
507 it is recommended to have exactly one.
510 A string applied as user tag. Often, it is a subproduct
511 identification, like '"cedet"' or '"tramp"' for the package
514 If there is no ':tag' entry, no bug numbers will be returned but a
515 list of existing user tags for ':user'.
517 Example. Get all user tags for the package '"emacs"':
519 (let ((debbugs-port "gnu.org"))
520 (debbugs-get-usertag :user "emacs"))
521 => ("www" "solaris" "ls-lisp" "cygwin")
523 Get all bugs tagged by package '"emacs"' with '"www"' or
526 (let ((debbugs-port "gnu.org"))
527 (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
534 Node: Installation
\7f3043
535 Node: Configuration
\7f4142
536 Node: Requesting bug numbers
\7f6048
537 Node: Requesting bugs statuses
\7f11276
538 Node: Requesting messages
\7f15327
539 Node: Requesting user tags
\7f18343