2 @setfilename debbugs.info
3 @settitle Debbugs programmer's manual
7 * Debbugs: (debbugs). A library for communication with Debbugs.
11 Copyright @copyright{} 2011-2016 Free Software Foundation, Inc.
14 Permission is granted to copy, distribute and/or modify this document
15 under the terms of the GNU Free Documentation License, Version 1.2 or
16 any later version published by the Free Software Foundation; with no
17 Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of
18 the license is included in the section entitled ``GNU Free Documentation
19 License'' in the Emacs manual.
21 This document is part of a collection distributed under the GNU Free
22 Documentation License. If you want to distribute this document
23 separately from the collection, you can do so by adding a copy of the
24 license to the document, as described in section 6 of the license.
26 All Emacs Lisp code contained in this document may be used, distributed,
27 and modified without restriction.
32 @title Debbugs Programmer's Manual
33 @author by Evgeny M. Zubok
41 @top Debbugs Programmer's Manual
43 Debbugs is a bugtracking system (BTS) that was initially written for
44 the Debian project but currently used also by the GNU project. The
45 main distinctive feature of Debbugs is that it's mostly email-based.
46 All actions on bug reports: opening, closing, changing the status,
47 commenting, forwarding are performed via email by sending specially
48 composed letters to the particular mail addresses. However, searching
49 the bug reports, querying bug report status and viewing comments have
50 been web-based for a long time. To overcome this inconvenience the
51 Debbugs/SOAP service was introduced.
53 The Debbugs/SOAP service provides the means for developers to write
54 client applications that can send the queries with certain search
55 criteria to the Debbugs server and retrieve a set of bug reports that
56 match them. The developer may also ask the Debbugs server for
57 additional information about every bug report (e.g. subject, date,
58 originator, tags and etc.) and get all comments and attachments.
60 @code{debbugs}, described in this document, is the Emacs library that
61 exposes to developers the available functions provided by the Debbugs
62 server. @code{debbugs} uses Emacs' SOAP client library for
63 communication with the Debbugs server. In tandem with Emacs' email
64 facilities, @code{debbugs} provides a solution for building
65 applications that interact with the Debbugs BTS directly from Emacs
66 without addressing Debbugs' web interface.
68 The user interface for accessing the Debbugs server for GNU projects
69 is described in @ref{Top, Debbugs User Guide, , debbugs-ug}.
72 * Installation:: Getting and installing @code{debbugs}.
73 * Configuration:: Configuring @code{debbugs}.
74 * Requesting bug numbers:: How to request bug report numbers.
75 * Requesting bugs statuses:: How to request the status of bug reports.
76 * Requesting messages:: How to get messages from bug reports.
77 * Requesting user tags:: How to request tags set by users.
83 @subheading Installation on Emacs 24 or later
85 Install @code{debbugs} from the @ref{Packaging, ELPA repository, , elisp}.
87 @subheading Installation on Emacs 22 and Emacs 23
89 If you want to install @code{debbugs} on Emacs 22/23, you will need to
90 install the @code{soap-client} library first. It can be downloaded from
91 the @uref{http://code.google.com/p/emacs-soap-client/, Emacs SOAP client
94 Compile the library and add it into your @code{load-path}:
97 (add-to-list 'load-path "/path/to/emacs-soap-client/")
100 @code{debbugs} library can be downloaded from the
101 @uref{http://elpa.gnu.org/packages/, ELPA repository}. Compile it and
102 set the @code{load-path}:
105 (add-to-list 'load-path "/path/to/debbugs/")
108 @subheading Installation on Emacs 21
110 We have not tried yet to install @code{debbugs} on Emacs 21. We would
111 definitely say that the installation will require even more additional
112 libraries than needed for installation on Emacs 22/23.
115 @chapter Configuration
117 @code{debbugs} is already configured to work with two main ports of
118 Debbugs BTS: @uref{http://bugs.debian.org} and
119 @uref{http://debbugs.gnu.org}. So if you intend to use one of these
120 ports, you don't need to configure @code{debbugs}. If you want to
121 interact with a Debbugs port other than those listed, you have to
122 configure @code{debbugs} by adding a new server specifier to the
123 @code{debbugs-servers} variable. The actual port can be selected by
124 the @code{debbugs-port} variable.
126 @defvar debbugs-servers
127 List of Debbugs server specifiers. Each entry is a list that contains a
128 string identifying the port name and the server parameters in
129 keyword-value form. The list initially contains two predefined and
130 configured Debbugs servers: @code{"gnu.org"} and @code{"debian.org"}.
136 Location of WSDL. The value is a string with the URL that should
137 return the WSDL specification of the Debbugs/SOAP service. This
138 keyword is intended for future use, it is ignored currently.
141 The URL of the server script (@code{bugreport.cgi} in the default
142 Debbugs installation) that provides the access to mboxes with messages
146 Example. Add a new Debbugs port with name "foobars.net":
152 :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
153 :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
158 This variable holds the name of the currently used port. The value of
159 the variable corresponds to the Debbugs server to be accessed, either
160 @code{"gnu.org"} or @code{"debian.org"}, or a user defined port name.
163 @defvar debbugs-cache-expiry
164 The function @code{debbugs-get-status} (@pxref{Requesting bugs
165 statuses}) caches retrieved status entries in order to improve the
166 performance. This variable determines the number of seconds an entry
167 is cached, before it is retrieved again. A value of @code{nil}
168 disables cache expiration, and a value of @code{t} disables caching.
169 Both values are not recommended for a usual workflow.
172 @node Requesting bug numbers
173 @chapter Requesting bug numbers
175 In Debbugs BTS, the bug number is the unique identifier of a bug
176 report. The functions described in this section return from the
177 Debbugs server the list of bug numbers that match a user's query.
179 @defun debbugs-get-bugs &rest query
180 This function returns a list of bug numbers that match the
181 @var{query}. @var{query} is a sequence of keyword-value pairs where the
182 values are strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
184 The keyword-value pair is a subquery. The keywords are allowed to
185 have multiple occurrence within the query at any place. The
186 subqueries with the same keyword form the logical subquery, which
187 returns the union of bugs of every subquery it contains.
189 The result of the @var{query} is an intersection of results of all
196 The value is the name of the package a bug belongs to, like @code{"emacs"},
197 @code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}.
200 This is used to retrieve bugs that belong to source with given name.
203 This is the severity of the bug. The exact set of available severities
204 depends on the policy of a particular Debbugs port:
207 @code{"critical"}, @code{"grave"}, @code{"serious"},
208 @code{"important"}, @code{"normal"}, @code{"minor"}, @code{"wishlist"},
212 @code{"serious"}, @code{"important"}, @code{"normal"}, @code{"minor"},
216 An arbitrary string the bug is annotated with. Usually, this is used
217 to mark the status of the bug. The list of possible tags depends on
220 Debian port: @code{"patch"}, @code{"wontfix"}, @code{"moreinfo"},
221 @code{"unreproducible"}, @code{"fixed"}, @code{"potato"},
222 @code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
223 @code{"upstream"}, @code{"pending"}, @code{"sarge"},
224 @code{"sarge-ignore"}, @code{"experimental"}, @code{"d-i"},
225 @code{"confirmed"}, @code{"ipv6"}, @code{"lfs"},
226 @code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"},
227 @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
228 @code{"lenny-ignore"}, @code{"squeeze"}, @code{"squeeze-ignore"},
229 @code{"wheezy"}, @code{"wheezy-ignore"}. The actual list of tags can be
230 found on @uref{http://www.debian.org/Bugs/Developer#tags}.
232 GNU port: @code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
233 @code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"},
234 @code{"pending"}, @code{"help"}, @code{"security"}, @code{"confirmed"}.
235 See @url{http://debbugs.gnu.org/Developer.html#tags} for the actual list
239 This is used to identify bugs by the owner's email address. The
240 special email address @code{"me"} is used as pattern, replaced with
241 the variable @code{user-mail-address} (@pxref{(elisp)User
245 With this keyword it is possible to filter bugs by the submitter's
246 email address. The special email address @code{"me"} is used as
247 pattern, replaced with the variable @code{user-mail-address}.
250 This is used to find bugs of the packages which are maintained by the
251 person with the given email address. The special email address
252 @code{"me"} is used as pattern, replaced with @code{user-mail-address}.
255 This allows to find bug reports where the person with the given email
256 address has participated. The special email address @code{"me"} is used
257 as pattern, replaced with @code{user-mail-address}.
260 With this keyword it is possible to find bugs which affect the package
261 with the given name. The bugs are chosen by the value of field
262 @code{affects} in bug's status. The returned bugs do not necessary
263 belong to this package.
266 Status of bug. Valid values are @code{"done"}, @code{"forwarded"} and
270 A keyword to filter for bugs which are already archived, or not. Valid
271 values are @code{"0"} (not archived), @code{"1"} (archived) or
272 @code{"both"}. If this keyword is not given in the query,
273 @code{:archive "0"} is assumed by default.
276 Example. Get all opened and forwarded release critical bugs for the
277 packages which are maintained by @code{"me"} and which have a patch:
280 (let ((debbugs-port "debian.org"))
281 (debbugs-get-bugs :maint "me" :tag "patch"
286 :severity "serious"))
290 @defun debbugs-newest-bugs amount
291 This function returns a list of bug numbers, according to @var{amount}
292 (a number) of latest bugs.
294 Example. Get the latest six bug report numbers from Debian BTS:
297 (let ((debbugs-port "debian.org"))
298 (debbugs-newest-bugs 6))
299 @result{} (633152 633153 633154 633155 633156 633157)
303 @node Requesting bugs statuses
304 @chapter Requesting bugs statuses
306 Bug status is a collection of fields that holds the information about
307 the state and importance of the bug report, about originator, owner and
308 various aspects of relationship with other bug reports.
310 @defun debbugs-get-status &rest bug-numbers
311 Return a list of status entries for the bug reports identified by
312 @var{bug-numbers}. Every returned entry is an association list with the
313 following attributes:
321 A list of package names the bug belongs to.
324 The severity of the bug report. Possible values are the same as for
325 @code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
329 The status of the bug report, a list of strings. Possible values are the
330 same as for @code{:tags} in @code{debbugs-get-bugs} (@pxref{Requesting
334 The string @code{"pending"}, @code{"forwarded"} or @code{"done"}.
337 Subject/Title of the bugreport.
340 The E-mail address of the bug report submitter.
343 A list of bug numbers this bug was merged with.
346 Source package name of the bug report.
349 Date of bug creation. Encoded as UNIX time.
353 Date of last update. Encoded as UNIX time.
357 Date of bug report / bug fix (empty for now). Encoded as UNIX time.
360 The E-mail address of the worker who has closed the bug (if done).
363 @code{t} if the bug is archived, @code{nil} otherwise.
366 The date the bug has been unarchived, if ever. Encoded as UNIX time.
369 @itemx fixed_versions
370 List of version strings.
373 A URL or an E-mail address.
376 A list of bug numbers this bug blocks.
379 A list of bug numbers this bug is blocked by.
382 The message id of the initial bug report.
385 Who is responsible for fixing.
388 Always the string @code{"db-h"} or @code{"archive"}.
391 A list of package names.
397 Example. Get the status of bug number #10 from GNU BTS:
400 (let ((debbugs-port "gnu.org"))
401 (debbugs-get-status 10))
403 (((source . "unknown") (found_versions) (done) (blocks)
404 (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
405 (found) (unarchived) (blockedby) (keywords) (summary)
406 (msgid . "<87zltuz7eh.fsf@@freemail.hu>") (id . 10)
407 (forwarded) (severity . "wishlist")
408 (owner . "Magnus Henoch <*****@@freemail.hu>")
409 (log_modified . 1310061242.0) (location . "db-h")
410 (subject . "url-gw should support HTTP CONNECT proxies")
411 (originator . "Magnus Henoch <*****@@freemail.hu>")
412 (last_modified . 1310061242.0) (pending . "pending") (affects)
413 (archived) (tags) (fixed_date) (package "emacs") (found_date)
418 @defun debbugs-get-attribute bug-or-message attribute
419 General accessor that returns the value of key @var{attribute}.
420 @var{bug-or-message} must be a list element returned by either
421 @code{debbugs-get-status} or @code{debbugs-get-bug-log}
422 (@pxref{Requesting messages}).
424 Example. Return the originator of the last submitted bug report:
427 (let ((debbags-port "gnu.org"))
428 (debbugs-get-attribute
429 (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
431 @result{} "Jack Daniels <jack@@daniels.com>"
435 @node Requesting messages
436 @chapter Requesting messages
438 @defun debbugs-get-bug-log bug-number
439 Returns a list of messages related to @var{bug-number}. Every message is
440 an association list with the following attributes:
444 The number of the message inside the bug log. The numbers are ascending,
445 newer messages have a higher number.
447 The header lines from the E-mail messages, as arrived at the bug
452 A list of possible attachments, or @code{nil}. Not implemented yet server
457 @defun debbugs-get-message-numbers messages
458 Returns the message numbers of @var{messages}. @var{messages} must be
459 the result of a @code{debbugs-get-bug-log} call.
461 Example. Get message numbers from bug report #456789 log from Debian
465 (let ((debbugs-port "debian.org"))
466 (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
471 @defun debbugs-get-message messages message-number
472 Returns the message @var{message-number} of
473 @var{messages}. @var{messages} must be the result of a
474 @code{debbugs-get-bug-log} call. The returned message is a list of
475 strings. The first element are the header lines of the message, the
476 second element is the body of the message. Further elements of the list,
477 if any, are attachments of the message. If there is no message with
478 @var{message-number}, the function returns @code{nil}.
480 Example: Return the first message of the last submitted bug report to
484 (let* ((debbugs-port "gnu.org")
485 (messages (apply 'debbugs-get-bug-log
486 (debbugs-newest-bugs 1))))
489 (car (debbugs-get-message-numbers messages))))
493 @defun debbugs-get-mbox bug-number mbox-type &optional filename
494 Download mbox with all messages from bug report
495 @var{bug-number}. @var{mbox-type} specifies a type of mbox and can be
496 one of the following symbols:
500 Download mbox folder, i.e. mbox with messages as they arrived at the
504 Download maintainer's mbox, i.e. mbox with messages as they are resent
505 from the Debbugs server.
509 Download status mbox. The use of either symbol depends on the actual
510 Debbugs server configuration. For @code{"gnu.org"}, use the former;
511 for @code{"debian.org} - the latter.
514 @var{filename}, if non-@code{nil}, is the name of the file to store
515 mbox. If @var{filename} is @code{nil}, the downloaded mbox is
516 inserted into the current buffer.
518 Note, that mbox downloading will work only if the
519 @code{:bugreport-url} field of the @code{debbugs-servers} variable is
520 specified (@pxref{Configuration}).
523 @node Requesting user tags
524 @chapter Requesting user tags
526 A user tag is a string, a user has assigned to one or several bugs.
527 The user is identified by an email address. The port @code{"gnu.org"}
528 uses also package names as user identification.
530 @defun debbugs-get-usertag &rest query
531 Return a list of bug numbers which match @var{query}.
533 @var{query} is a sequence of keyword-value pairs where the values are
534 strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
540 The value is the name of the package a bug belongs to, like
541 @code{"emacs"}, @code{"coreutils"}, or @code{"tramp"}. It can also be
542 an email address of a user who has applied a user tag. The special
543 email address @code{"me"} is used as pattern, replaced with
544 @code{user-mail-address}. There must be at least one such entry; it
545 is recommended to have exactly one.
548 A string applied as user tag. Often, it is a subproduct
549 identification, like @code{"cedet"} or @code{"tramp"} for the package
553 If there is no @code{:tag} entry, no bug numbers will be returned but
554 a list of existing user tags for @code{:user}.
556 Example. Get all user tags for the package @code{"emacs"}:
559 (let ((debbugs-port "gnu.org"))
560 (debbugs-get-usertag :user "emacs"))
561 @result{} ("www" "solaris" "ls-lisp" "cygwin")
564 Get all bugs tagged by package @code{"emacs"} with @code{"www"} or
568 (let ((debbugs-port "gnu.org"))
569 (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
570 @result{} (807 1223 5637)