Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of
+Invariant Sections, with the Front-Cover, or Back-Cover Texts. A copy of
the license is included in the section entitled ``GNU Free Documentation
License'' in the Emacs manual.
@end quotation
@end copying
+@titlepage
+@title Debbugs Programmer's Manual
+@author by Evgeny M. Zubok
+@page
+@insertcopying
+@end titlepage
+
+@contents
+
@node Top
-@top Debbugs programmer's manual
+@top Debbugs Programmer's Manual
+
Debbugs is a bugtracking system (BTS) that was initially written for
-Debian project but actually used also by GNU project. The main
-distinctive feature of Debbugs is that it's mostly email-based. All
-actions on bug reports: opening, closing, changing the status,
+the Debian project but actually used also by the GNU project. The
+main distinctive feature of Debbugs is that it's mostly email-based.
+All actions on bug reports: opening, closing, changing the status,
commenting, forwarding are performed via email by sending specially
-composed letters to the partucular mail addresses. However, searching
+composed letters to the particular mail addresses. However, searching
the bug reports, querying bug report status and viewing comments have
-been web-based for a long time. To overcome this inconvinience the
+been web-based for a long time. To overcome this inconvenience the
Debbugs/SOAP service was introduced.
-Debbugs/SOAP service provides the means for developer to write client
-application that can send the queries with certain search criteria to
-Debbugs server and retrieve a set of bug reports that match them. The
-developer may also ask Debbugs server for additional information about
-every bug report (e. g. subject, date, originator, tags and etc.) and
-get all comments and attachments.
+The Debbugs/SOAP service provides the means for developers to write
+client applications that can send the queries with certain search
+criteria to the Debbugs server and retrieve a set of bug reports that
+match them. The developer may also ask the Debbugs server for
+additional information about every bug report (e.g. subject, date,
+originator, tags and etc.) and get all comments and attachments.
@code{debbugs}, described in this document, is the Emacs library that
-exposes to developer the available functions provided by Debbugs
-server. @code{debbugs} uses Emacs SOAP client library for communication
-with Debbugs server. In tandem with Emacs email facilities,
-@code{debbugs} provides a solution for building application that
-interacts with Debbugs BTS directly from Emacs without addressing
-Debbugs' web interface.
+exposes to developers the available functions provided by the Debbugs
+server. @code{debbugs} uses Emacs' SOAP client library for
+communication with the Debbugs server. In tandem with Emacs' email
+facilities, @code{debbugs} provides a solution for building
+applications that interact with the Debbugs BTS directly from Emacs
+without addressing Debbugs' web interface.
@menu
* Installation:: Getting and installing @code{debbugs}.
* Configuration:: Configuring @code{debbugs}.
* Requesting bug numbers:: How to request bug report numbers.
-* Requesting bugs statuses:: How to request status of bug report.
-* Requesting messages:: How to get messages from bug report.
+* Requesting bugs statuses:: How to request the status of bug reports.
+* Requesting messages:: How to get messages from bug reports.
+* Requesting user tags:: How to request tags set by users.
@end menu
@node Installation
@chapter Installation
@subheading Installation on Emacs 24 or later
-Install @code{debbugs} from ELPA repository.
+
+Install @code{debbugs} from the @ref{Packaging, ELPA repository, , elisp}.
@subheading Installation on Emacs 22 and Emacs 23
+
If you want to install @code{debbugs} on Emacs 22/23, you will need to
-install @code{soap-client} library first. It can be downloaded from
-@uref{http://code.google.com/p/emacs-soap-client/, Emacs SOAP client
+install the @code{soap-client} library first. It can be downloaded from
+the @uref{http://code.google.com/p/emacs-soap-client/, Emacs SOAP client
project page}.
Compile the library and add it into your @code{load-path}:
(add-to-list 'load-path "/path/to/emacs-soap-client/")
@end example
-@code{debbugs} library can be downloaded from
-@uref{http://elpa.gnu.org/packages/, ELPA repository}. Compile it and
-set the @code{load-path}:
+@code{debbugs} library can be downloaded from the
+@uref{http://elpa.gnu.org/packages/, ELPA repository}. Compile it and
+set the @code{load-path}:
@example
(add-to-list 'load-path "/path/to/debbugs/")
@end example
@subheading Installation on Emacs 21
-We have not tried yet to install @code{debbugs} on Emacs 21. We would
+
+We have not tried yet to install @code{debbugs} on Emacs 21. We would
definitely say that the installation will require even more additional
libraries than needed for installation on Emacs 22/23.
@node Configuration
@chapter Configuration
+
@code{debbugs} is already configured to work with two main ports of
Debbugs BTS: @uref{http://bugs.debian.org} and
-@uref{http://debbugs.gnu.org}. So if you intend to use these ports, you
-don't need to configure @code{debbugs}. If you want to interact with
-Debbugs port other than those listed, you have to configure
-@code{debbugs} by adding a new server specifier to
-@code{debbugs-servers} variable. The actual port can be selected by
-@code{debbugs-port} variable.
+@uref{http://debbugs.gnu.org}. So if you intend to use one of these
+ports, you don't need to configure @code{debbugs}. If you want to
+interact with a Debbugs port other than those listed, you have to
+configure @code{debbugs} by adding a new server specifier to the
+@code{debbugs-servers} variable. The actual port can be selected by
+the @code{debbugs-port} variable.
@defvar debbugs-servers
-List of Debbugs server specifiers. Each entry is a list that contains a
+List of Debbugs server specifiers. Each entry is a list that contains a
string identifying the port name and the server parameters in
-keyword-value form. The list initially contains two predefined and
+keyword-value form. The list initially contains two predefined and
configured Debbugs servers: @code{"gnu.org"} and @code{"debian.org"}.
Valid keywords are:
@table @code
@item :wsdl
-Location of WSDL. The value is a string with URL that should return the
-WSDL specification of Debbugs/SOAP service. This keyword is intended for
-future use and currently is ignored.
+Location of WSDL. The value is a string with the URL that should
+return the WSDL specification of the Debbugs/SOAP service. This
+keyword is intended for future use, it is ignored currently.
+
@item :bugreport-url
-URL of the server script (@code{bugreport.cgi} in default Debbugs
-installation) that provides the access to mboxes with messages from bug
-reports.
+The URL of the server script (@code{bugreport.cgi} in the default
+Debbugs installation) that provides the access to mboxes with messages
+from bug reports.
@end table
-Example. Add new Debbugs port with name "foobars.net":
+Example. Add a new Debbugs port with name "foobars.net":
@example
-(add-to-list
- 'debbugs-servers
+(add-to-list
+ 'debbugs-servers
'("foobars.net"
:wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
:bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
@end defvar
@defvar debbugs-port
-This variable holds the name of currently used port. Value of the
-variable corresponds to the Debbugs server to be accessed, either
-"gnu.org", or "debian.org", or user defined port name.
+This variable holds the name of the currently used port. The value of
+the variable corresponds to the Debbugs server to be accessed, either
+@code{"gnu.org"} or @code{"debian.org"}, or a user defined port name.
@end defvar
@node Requesting bug numbers
@chapter Requesting bug numbers
-In Debbugs BTS, the bug number is the unique identifier of bug
-report. The functions described in this section return from Debbugs
-server the list of bug numbers that match user's query.
+
+In Debbugs BTS, the bug number is the unique identifier of a bug
+report. The functions described in this section return from the
+Debbugs server the list of bug numbers that match a user's query.
@defun debbugs-get-bugs &rest query
This function returns a list of bug numbers that match the
-@var{query}. The @var{query} is a key-value pair sequence, where the key
-is a keyword (symbol) and the value is a string. All queries are
-logically concatenated via AND.
+@var{query}. @var{query} is a sequence of keyword-value pairs where the
+values are strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
+
+The keyword-value pair is a subquery. The keywords are allowed to
+have multiple occurrence within the query at any place. The
+subqueries with the same keyword form the logical subquery, which
+returns the union of bugs of every subquery it contains.
+
+The result of the @var{query} is an intersection of results of all
+subqueries.
Valid keywords are:
@item :package
The value is the name of the package a bug belongs to, like @code{"emacs"},
@code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}.
+
+@item :src
+This is used to retrieve bugs that belong to source with given name.
+
@item :severity
-This is the severity of the bug. The exact set of available severities
-depends on policy of particular Debbugs port:
+This is the severity of the bug. The exact set of available severities
+depends on the policy of a particular Debbugs port:
Debian port:
@code{"critical"}, @code{"grave"}, @code{"serious"},
@code{"important"}, @code{"normal"}, @code{"minor"}, @code{"wishlist"},
and @code{"fixed"}.
-GNU port:
-@code{"important"}, @code{"grave"}, @code{"normal"}, @code{"minor"},
+GNU port:
+@code{"serious"}, @code{"important"}, @code{"normal"}, @code{"minor"},
@code{"wishlist"}.
-@item :tag
-An arbitrary string the bug is annotated with. Usually, this is used to
-mark the status of the bug. The list of possible tags depends on Debbugs
-port.
-Debian port:
-@code{"patch"}, @code{"wontfix"}, @code{"moreinfo"},
+@item :tag
+An arbitrary string the bug is annotated with. Usually, this is used
+to mark the status of the bug. The list of possible tags depends on
+the Debbugs port.
+
+Debian port: @code{"patch"}, @code{"wontfix"}, @code{"moreinfo"},
@code{"unreproducible"}, @code{"fixed"}, @code{"potato"},
@code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
@code{"upstream"}, @code{"pending"}, @code{"sarge"},
@code{"confirmed"}, @code{"ipv6"}, @code{"lfs"},
@code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"},
@code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
-@code{"lenny-ignore"}.
+@code{"lenny-ignore"}, @code{"squeeze"}, @code{"squeeze-ignore"},
+@code{"wheezy"}, @code{"wheezy-ignore"}. The actual list of tags can be
+found on @uref{http://www.debian.org/Bugs/Developer#tags}.
+
+GNU port: @code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
+@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"},
+@code{"pending"}, @code{"help"}, @code{"security"}, @code{"confirmed"}.
+See @url{http://debbugs.gnu.org/Developer.html#tags} for the actual list
+of tags.
-GNU port:
-@code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
-@code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"}.
@item :owner
-This is used to identify bugs by the owner's email address. The special
-email address @code{"me"} is used as pattern, replaced with variable
-@code{user-mail-address} (@pxref{(elisp)User Identification})
+This is used to identify bugs by the owner's email address. The
+special email address @code{"me"} is used as pattern, replaced with
+the variable @code{user-mail-address} (@pxref{(elisp)User
+Identification}).
+
@item :submitter
-With this keyword it is possible to filter bugs by the submitter's email
-address. The special email address @code{"me"} is used as pattern,
-replaced with variable @code{user-mail-address}.
+With this keyword it is possible to filter bugs by the submitter's
+email address. The special email address @code{"me"} is used as
+pattern, replaced with the variable @code{user-mail-address}.
+
+@item :maint
+This is used to find bugs of the packages which are maintained by the
+person with the given email address. The special email address
+@code{"me"} is used as pattern, replaced with @code{user-mail-address}.
+
+@item :correspondent
+This allows to find bug reports where the person with the given email
+address has participated. The special email address @code{"me"} is used
+as pattern, replaced with @code{user-mail-address}.
+
+@item :affects
+With this keyword it is possible to find bugs which affect the package
+with the given name. The bugs are chosen by the value of field
+@code{affects} in bug's status. The returned bugs do not necessary
+belong to this package.
+
+@item :status
+Status of bug. Valid values are @code{"done"}, @code{"forwarded"} and
+@code{"open"}.
+
@item :archive
A keyword to filter for bugs which are already archived, or not. Valid
values are @code{"0"} (not archived), @code{"1"} (archived) or
-@code{"both"}. If this keyword is not given in the query, @code{:archive
-"0"} is assumed by default.
+@code{"both"}. If this keyword is not given in the query,
+@code{:archive "0"} is assumed by default.
@end table
-Example. Get all bug reports that were initiated by me.
+Example. Get all opened and forwarded release critical bugs for the
+packages which are maintained by @code{"me"} and which have a patch:
@example
-(let ((debbugs-port "gnu.org"))
- (debbugs-get-bugs :submitter "me" :archive "both"))
-@result{} (5516 5551 5645 7259)
+(let ((debbugs-port "debian.org"))
+ (debbugs-get-bugs :maint "me" :tag "patch"
+ :severity "critical"
+ :status "open"
+ :severity "grave"
+ :status "forwarded"
+ :severity "serious"))
@end example
@end defun
This function returns a list of bug numbers, according to @var{amount}
(a number) of latest bugs.
-Example. Get the latest six bug report numbers from Debian BTS:
+Example. Get the latest six bug report numbers from Debian BTS:
@example
(let ((debbugs-port "debian.org"))
@node Requesting bugs statuses
@chapter Requesting bugs statuses
+
Bug status is a collection of fields that holds the information about
the state and importance of the bug report, about originator, owner and
various aspects of relationship with other bug reports.
@defun debbugs-get-status &rest bug-numbers
Return a list of status entries for the bug reports identified by
-@var{bug-numbers}. Every returned entry is an association list with the
+@var{bug-numbers}. Every returned entry is an association list with the
following attributes:
@table @code
-@item bug_num
+@item id
+@itemx bug_num
The bug number.
+
@item package
A list of package names the bug belongs to.
+
@item severity
-The severity of the bug report. Possible values are the same as for
+The severity of the bug report. Possible values are the same as for
@code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
numbers}).
+
@item tags
-The status of the bug report, a list of strings. Possible values are the
+The status of the bug report, a list of strings. Possible values are the
same as for @code{:tags} in @code{debbugs-get-bugs} (@pxref{Requesting
bug numbers}).
+
@item pending
The string @code{"pending"}, @code{"forwarded"} or @code{"done"}.
+
@item subject
Subject/Title of the bugreport.
+
@item originator
-The E-mail address of bug report submitter.
+The E-mail address of the bug report submitter.
+
@item mergedwith
A list of bug numbers this bug was merged with.
+
@item source
Source package name of the bug report.
+
@item date
-Date of bug creation. Encoded as UNIX time.
+Date of bug creation. Encoded as UNIX time.
+
@item log_modified
-@item last_modified
-Date of last update. Encoded as UNIX time.
+@itemx last_modified
+Date of last update. Encoded as UNIX time.
+
@item found_date
-@item fixed_date
-Date of bug report / bug fix (empty for now). Encoded as UNIX time.
+@itemx fixed_date
+Date of bug report / bug fix (empty for now). Encoded as UNIX time.
+
@item done
The E-mail address of the worker who has closed the bug (if done).
+
@item archived
@code{t} if the bug is archived, @code{nil} otherwise.
+
@item unarchived
-The date the bug has been unarchived, if ever. Encoded as UNIX time.
+The date the bug has been unarchived, if ever. Encoded as UNIX time.
+
@item found_versions
-@item fixed_versions
+@itemx fixed_versions
List of version strings.
+
@item forwarded
A URL or an E-mail address.
+
@item blocks
A list of bug numbers this bug blocks.
+
@item blockedby
A list of bug numbers this bug is blocked by.
+
@item msgid
The message id of the initial bug report.
+
@item owner
Who is responsible for fixing.
+
@item location
Always the string @code{"db-h"} or @code{"archive"}.
+
@item affects
A list of package names.
+
@item summary
Arbitrary text.
@end table
-Example. Get status of bug number #10 from GNU BTS:
+Example. Get the status of bug number #10 from GNU BTS:
@example
(let ((debbugs-port "gnu.org"))
(debbugs-get-status 10))
@result{}
(((source . "unknown") (found_versions) (done) (blocks)
- (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
- (found) (unarchived) (blockedby) (keywords) (summary)
- (msgid . "<87zltuz7eh.fsf@@freemail.hu>") (id . 10)
- (forwarded) (severity . "wishlist")
+ (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
+ (found) (unarchived) (blockedby) (keywords) (summary)
+ (msgid . "<87zltuz7eh.fsf@@freemail.hu>") (id . 10)
+ (forwarded) (severity . "wishlist")
(owner . "Magnus Henoch <*****@@freemail.hu>")
- (log_modified . 1310061242.0) (location . "db-h")
- (subject . "url-gw should support HTTP CONNECT proxies")
+ (log_modified . 1310061242.0) (location . "db-h")
+ (subject . "url-gw should support HTTP CONNECT proxies")
(originator . "Magnus Henoch <*****@@freemail.hu>")
- (last_modified . 1310061242.0) (pending . "pending") (affects)
- (archived) (tags) (fixed_date) (package "emacs") (found_date)
+ (last_modified . 1310061242.0) (pending . "pending") (affects)
+ (archived) (tags) (fixed_date) (package "emacs") (found_date)
(bug_num . 10)))
@end example
@end defun
@defun debbugs-get-attribute bug-or-message attribute
-General accessor that returns the value of key
-@var{attribute}. @var{bug-or-message} must be list element returned by
-either @code{debbugs-get-status} or @code{debbugs-get-bug-log}.
+General accessor that returns the value of key @var{attribute}.
+@var{bug-or-message} must be a list element returned by either
+@code{debbugs-get-status} or @code{debbugs-get-bug-log}
+(@pxref{Requesting messages}).
-Example. Return the originator of last submitted bug report:
+Example. Return the originator of the last submitted bug report:
@example
(let ((debbags-port "gnu.org"))
@chapter Requesting messages
@defun debbugs-get-bug-log bug-number
-Returns a list of messages related to @var{bug-number}. Every message is
+Returns a list of messages related to @var{bug-number}. Every message is
an association list with the following attributes:
@table @code
@item msg_num
-The number of the message inside the bug log. The numbers are ascending,
+The number of the message inside the bug log. The numbers are ascending,
newer messages have a higher number.
@item header
The header lines from the E-mail messages, as arrived at the bug
@item body
The message body.
@item attachments
-A list of possible attachments, or @code{nil}. Not implemented yet server
+A list of possible attachments, or @code{nil}. Not implemented yet server
side.
@end table
@end defun
@defun debbugs-get-message-numbers messages
-Returns the message numbers of @var{messages}. @var{messages} must be
+Returns the message numbers of @var{messages}. @var{messages} must be
the result of a @code{debbugs-get-bug-log} call.
-Example. Get message numbers from bug report #456789 log from Debian
+Example. Get message numbers from bug report #456789 log from Debian
BTS:
@example
@defun debbugs-get-message messages message-number
Returns the message @var{message-number} of
-@var{messages}. @var{messages} must be the result of a
-@code{debbugs-get-bug-log} call. The returned message is a list of
-strings. The first element are the header lines of the message, the
-second element is the body of the message. Further elements of the list,
-if any, are attachments of the message. If there is no message with
+@var{messages}. @var{messages} must be the result of a
+@code{debbugs-get-bug-log} call. The returned message is a list of
+strings. The first element are the header lines of the message, the
+second element is the body of the message. Further elements of the list,
+if any, are attachments of the message. If there is no message with
@var{message-number}, the function returns @code{nil}.
-Example: Return the first message of last submitted bug report to Debian
-BTS:
+Example: Return the first message of the last submitted bug report to
+GNU BTS:
@example
(let* ((debbugs-port "gnu.org")
- (messages (apply 'debbugs-get-bug-log
+ (messages (apply 'debbugs-get-bug-log
(debbugs-newest-bugs 1))))
- (debbugs-get-message
+ (debbugs-get-message
messages
(car (debbugs-get-message-numbers messages))))
@end example
@defun debbugs-get-mbox bug-number mbox-type &optional filename
Download mbox with all messages from bug report
-@var{bug-number}. @var{mbox-type} specifies a type of mbox and can be
+@var{bug-number}. @var{mbox-type} specifies a type of mbox and can be
one of the following symbols:
@table @code
@item mboxfolder
-Download mbox folder, i. e. mbox with messages as they arrived at
+Download mbox folder, i.e. mbox with messages as they arrived at the
Debbugs server.
+
@item mboxmaint
-Download maintainer's mbox, i. e. mbox with messages as they are
-resended from Debbugs server.
+Download maintainer's mbox, i.e. mbox with messages as they are resent
+from the Debbugs server.
+
@item mboxstat
-@item mboxstatus
-Download status mbox. The use of either symbol depends on actual Debbugs
-server configuration. For gnu.org, use the former; for debian.org - the
-latter.
+@itemx mboxstatus
+Download status mbox. The use of either symbol depends on the actual
+Debbugs server configuration. For @code{"gnu.org"}, use the former;
+for @code{"debian.org} - the latter.
+@end table
+
+@var{filename}, if non-@code{nil}, is the name of the file to store
+mbox. If @var{filename} is @code{nil}, the downloaded mbox is
+inserted into the current buffer.
+
+Note, that mbox downloading will work only if the
+@code{:bugreport-url} field of the @code{debbugs-servers} variable is
+specified (@pxref{Configuration}).
+@end defun
+
+@node Requesting user tags
+@chapter Requesting user tags
+
+A user tag is a string, a user has assigned to one or several bugs.
+The user is identified by an email address. The port @code{"gnu.org"}
+uses also package names as user identification.
+
+@defun debbugs-get-usertag &rest query
+Return a list of bug numbers which match @var{query}.
+
+@var{query} is a sequence of keyword-value pairs where the values are
+strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
+
+Valid keywords are:
+
+@table @code
+@item :user
+The value is the name of the package a bug belongs to, like
+@code{"emacs"}, @code{"coreutils"}, or @code{"tramp"}. It can also be
+an email address of a user who has applied a user tag. The special
+email address @code{"me"} is used as pattern, replaced with
+@code{user-mail-address}. There must be at least one such entry; it
+is recommended to have exactly one.
+
+@item :tag
+A string applied as user tag. Often, it is a subproduct
+identification, like @code{"cedet"} or @code{"tramp"} for the package
+@code{"emacs"}.
@end table
-@var{filename}, if non-@code{nil}, is the name of file to store mbox. If
-@var{filename} is @code{nil}, the downloaded mbox is inserted into the
-current buffer.
+If there is no @code{:tag} entry, no bug numbers will be returned but
+a list of existing user tags for @code{:user}.
+
+Example. Get all user tags for the package @code{"emacs"}:
-Note that mbox downloading will work only if the @code{:bugreport-url}
-field of @code{debbugs-servers} variable is specified
-(@pxref{Configuration}).
+@example
+(let ((debbugs-port "gnu.org"))
+ (debbugs-get-usertag :user "emacs"))
+@result{} ("www" "solaris" "ls-lisp" "cygwin")
+@end example
+
+Get all bugs tagged by package @code{"emacs"} with @code{"www"} or
+@code{"cygwin"})):
+
+@example
+(let ((debbugs-port "gnu.org"))
+ (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
+@result{} (807 1223 5637)
+@end example
@end defun
@bye