1 Installation

Installation on Emacs 24 or later

Install debbugs from the (elisp)ELPA repository.

Installation on Emacs 22 and Emacs 23

If you want to install debbugs on Emacs 22/23, you will need to install the soap-client library first. It can be downloaded from the Emacs SOAP client project page.

Compile the library and add it into your load-path:

(add-to-list 'load-path "/path/to/emacs-soap-client/")

debbugs library can be downloaded from the ELPA repository. Compile it and set the load-path:

(add-to-list 'load-path "/path/to/debbugs/")

Installation on Emacs 21

We have not tried yet to install 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.

2 Configuration

debbugs is already configured to work with two main ports of Debbugs BTS: https://bugs.debian.org and https://debbugs.gnu.org. So if you intend to use one of these ports, you don’t need to configure debbugs. If you want to interact with a Debbugs port other than those listed, you have to configure debbugs by adding a new server specifier to the debbugs-servers user option. The actual port can be selected by the debbugs-port user option.

User Option: debbugs-servers ¶

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 configured Debbugs servers: "gnu.org" and "debian.org".

Valid keywords are:

:wsdl

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.

:bugreport-url

The URL of the server script (bugreport.cgi in the default Debbugs installation) that provides the access to mboxes with messages from bug reports.

Example. Add a new Debbugs port with name "foobars.net":

(add-to-list
 'debbugs-servers
 '("foobars.net"
   :wsdl "https://bugs.foobars.net/cgi/soap.cgi?WSDL"
   :bugreport-url "https://bugs.foobars.net/cgi/bugreport.cgi"))

User Option: debbugs-port ¶

This user option holds the name of the currently used port. The value of the user option corresponds to the Debbugs server to be accessed, either "gnu.org" or "debian.org", or a user defined port name.

User Option: debbugs-cache-expiry ¶

The function debbugs-get-status (see Requesting bugs statuses) caches retrieved status entries in order to improve the performance. This user option determines the number of seconds an entry is cached, before it is retrieved again. A value of nil disables cache expiration, and a value of t disables caching. Both values are not recommended for a usual workflow.

User Option: debbugs-show-progress ¶

If this user option is non-nil, there is a progress report when retrieving bugs.

3 Requesting bug numbers

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.

Function: debbugs-get-bugs &rest query ¶

This function returns a list of bug numbers that match the query. 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 query is an intersection of results of all subqueries.

Valid keywords are:

:package

The value is the name of the package a bug belongs to, like "emacs", "coreutils", "gnus", or "tramp".

:src

This is used to retrieve bugs that belong to source with given name.

:severity

This is the severity of the bug. The exact set of available severities depends on the policy of a particular Debbugs port:

Debian port: "critical", "grave", "serious", "important", "normal", "minor", "wishlist", and "fixed".

GNU port: "serious", "important", "normal", "minor", "wishlist".

: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: "patch", "wontfix", "moreinfo", "unreproducible", "fixed", "potato", "woody", "sid", "help", "security", "upstream", "pending", "sarge", "sarge-ignore", "experimental", "d-i", "confirmed", "ipv6", "lfs", "fixed-in-experimental", "fixed-upstream", "l10n", "etch", "etch-ignore", "lenny", "lenny-ignore", "squeeze", "squeeze-ignore", "wheezy", "wheezy-ignore", "jessie", "jessie-ignore", "stretch", "stretch-ignore", "buster", "buster-ignore". The actual list of tags can be found on https://www.debian.org/Bugs/Developer#tags.

GNU port: "fixed", "notabug", "wontfix", "unreproducible", "moreinfo", "patch", "pending", "help", "security", "confirmed", "easy". See https://debbugs.gnu.org/Developer.html#tags for the actual list of tags.

:owner

This is used to identify bugs by the owner’s email address. The special email address "me" is used as pattern, replaced with the variable user-mail-address (see (elisp)User Identification).

:submitter

With this keyword it is possible to filter bugs by the submitter’s email address. The special email address "me" is used as pattern, replaced with the variable user-mail-address.

: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 "me" is used as pattern, replaced with user-mail-address.

:correspondent

This allows to find bug reports where the person with the given email address has participated. The special email address "me" is used as pattern, replaced with user-mail-address.

: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 affects in bug’s status. The returned bugs do not necessary belong to this package.

:status

Status of bug. Valid values are "open", "forwarded" and "done".

:archive

A keyword to filter for bugs which are already archived, or not. Valid values are "0" (not archived), "1" (archived) or "both". If this keyword is not given in the query, :archive "0" is assumed by default.

Example. Get all opened and forwarded release critical bugs for the packages which are maintained by "me" and which have a patch:

(let ((debbugs-port "debian.org"))
  (debbugs-get-bugs :maint "me" :tag "patch"
                    :severity "critical"
                    :status "open"
                    :severity "grave"
                    :status "forwarded"
                    :severity "serious"))

Function: debbugs-newest-bugs amount ¶

This function returns a list of bug numbers, according to amount (a number) of latest bugs.

Example. Get the latest six bug report numbers from Debian BTS:

(let ((debbugs-port "debian.org"))
  (debbugs-newest-bugs 6))

⇒ (633152 633153 633154 633155 633156 633157)

4 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.

Function: debbugs-get-status &rest bug-numbers ¶

Return a list of status entries for the bug reports identified by bug-numbers. Every returned entry is an association list with the following attributes:

id

bug_num

The bug number.

package

A list of package names the bug belongs to.

severity

The severity of the bug report. Possible values are the same as for :severity in debbugs-get-bugs (see Requesting bug numbers).

tags

The status of the bug report, a list of strings. Possible values are the same as for :tags in debbugs-get-bugs (see Requesting bug numbers).

pending

The string "pending", "forwarded", "fixed" or "done".

subject

Subject/Title of the bugreport.

originator

The E-mail address of the bug report submitter.

mergedwith

A list of bug numbers this bug was merged with.

source

Source package name of the bug report.

date

Date of bug creation. Encoded as UNIX time.

log_modified

last_modified

Date of last update. Encoded as UNIX time.

found_date

fixed_date

Date of bug report / bug fix (empty for now). Encoded as UNIX time.

done

The E-mail address of the worker who has closed the bug (if done).

archived

t if the bug is archived, nil otherwise.

unarchived

The date the bug has been unarchived, if ever. Encoded as UNIX time.

found_versions

fixed_versions

List of version strings.

forwarded

A URL or an E-mail address.

blocks

A list of bug numbers this bug blocks.

blockedby

A list of bug numbers this bug is blocked by.

msgid

The message id of the initial bug report.

owner

Who is responsible for fixing.

location

Always the string "db-h" or "archive".

affects

A list of package names.

summary

Arbitrary text.

cache_time

This is not an attribute located at the debbugs server, but an internal value of the debbugs.el package itself.

Example. Get the status of bug number #10 from GNU BTS:

(let ((debbugs-port "gnu.org"))
  (debbugs-get-status 10))

⇒ (((cache_time . 1469716026.4981334)
     (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")
     (owner . "Magnus Henoch <*****@freemail.hu>")
     (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)
     (bug_num . 10)))

Function: debbugs-get-attribute bug-or-message attribute ¶

General accessor that returns the value of key attribute. bug-or-message must be a list element returned by either debbugs-get-status or debbugs-get-bug-log (see Requesting messages).

Example. Return the originator of the last submitted bug report:

(let ((debbags-port "gnu.org"))
  (debbugs-get-attribute
   (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
   'originator))

⇒ "Jack Daniels <jack@daniels.com>"

5 Searching bugs

The Debbugs servers include an hyperestraier search engine, which allows to search inside the bug database. This is enabled only for the GNU port of the BTS, and also only the GNU port offers a Debbugs/SOAP interface for access.

The search engine uses an index over the bug database. This index is refreshed once a day only; search hits do not include recent changes of the same day.

Function: debbugs-search-est &rest query ¶

Return the result of a full text search according to query.

query is a sequence of lists of keyword-value pairs where the values are strings or numbers, i.e. :keyword value [:keyword value]*

Every sublist of the query forms a hyperestraier condition. A detailed description of hyperestraier conditions can be found at https://fallabs.com/hyperestraier/uguide-en.html#searchcond.

The following conditions are possible:

• (:phrase search-phrase :skip number :max number)

  The string search-phrase forms the search on the database. It contains words to be searched for, combined by operators like AND, ANDNOT and OR. If there is no operator between the words, AND is used by default. The phrase keyword and value can also be omitted, this is useful in combination with other conditions.

  :skip and :max are optional. They specify, how many hits are skipped, and how many maximal hits are returned. This can be used for paged results. Per default, :skip is 0 and all possible hits are returned according to the default maximum of the debbugs server. There is also an absolute maximum how many hits are returned by the debbugs server, which cannot be overwritten my any larger :max number.

  There must be exactly one such condition.

• (attribute value+ :operator operator :order order)

  attribute is one of the following keywords:

  :subject

  :@title

  The subject of a message or the title of the bug, a string.

  :date

  :@cdate

  The submission date of the bug or the modification date of a message, a number.

  :@author

  The email address of the author of a message belonging to this bug, a string. It may be different than the email of the person submitting the bug. The special email address "me" is used as pattern, replaced with user-mail-address.

  :package

  The value is the name of the package a bug belongs to, like "emacs", "coreutils", "gnus", or "tramp".

  :tags

  An arbitrary string the bug is annotated with.

  :severity

  This is the severity of the bug. The exact set of allowed values depends on the Debbugs port. Examples are "normal", "minor", "wishlist" etc.

  :operator defines the comparison operator to be applied to attribute. For string attributes this could be "STREQ" (is equal to the string), "STRNE" (is not equal to the string), "STRINC" (includes the string), "STRBW" (begins with the string), "STREW" (ends with the string), "STRAND" (includes all tokens in the string), "STROR" (includes at least one token in the string), "STROREQ" (is equal to at least one token in the string) or "STRRX" (matches regular expressions of the string). For operators with tokens, several values for attribute shall be used.

  Numbers can be compared by the operators "NUMEQ" (is equal to the number), "NUMNE" (is not equal to the number), "NUMGT" (is greater than the number), "NUMGE" (is greater than or equal to the number), "NUMLT" (is less than the number), "NUMLE" (is less than or equal to the number) or "NUMBT" (is between the two numbers). In the last case, there must be two values for attribute.

  If an operator is led by "!", the meaning is inverted. If a string operator is led by "I", the case of the value is ignored.

  The optional :order can be specified only in one condition. It means, that attribute is used for sorting the results. The following order operators exist: "STRA" (ascending by string), "STRD" (descending by string), "NUMA" (ascending by number) or "NUMD" (descending by number).

  A special case is an :order, where there is no corresponding attribute value and no operator. In this case, attribute is not used for the search.

  The result of the query is a list of association lists with the same attributes as in the conditions. Additional attributes are

  id

  The bug number.

  msg_num

  The number of the message inside the bug log.

  snippet

  The surrounding text found by the search. For the syntax of the snippet, consult the hyperestraier user guide.

Example. Get two messages containing words "armstrong" and "debbugs" from GNU BTS. Skip the first 10 hits:

(let ((debbugs-port "gnu.org"))
  (debbugs-search-est
    '(:phrase "armstrong AND debbugs" :skip 10 :max 2)
    '(:severity "normal" :operator "STRINC")
    '(:date :order "NUMA")))

⇒ ((("msg_num" . 21)
     ("date" . 1229208302)
     ("@author" . "Glenn Morris <*****@gnu.org>")
     ("@title" . "Re: bug#1567: Mailing an archived bug")
     ("id" . 1567)
     ("severity" . "normal")
     ("@cdate" . "Wed, 17 Dec 2008 14:34:50 -0500")
     ("snippet" . "…")
     ("subject" . "Mailing an archived bug")
     ("package" . "debbugs.gnu.org"))
 …)

Example. Show all messages for package "emacs" on GNU BTS between 2011-08-21 and 2011-08-31.

(let ((debbugs-port "gnu.org"))
  (debbugs-search-est
   '(:max 500)
   '(:package "emacs" :operator "STREQ")
   `(:@cdate
     ,(floor (float-time (encode-time 0 0 0 21 8 2011)))
     ,(floor (float-time (encode-time 0 0 0 31 8 2011)))
     :operator "NUMBT")))

6 Requesting messages

Function: debbugs-get-bug-log bug-number ¶

Returns a list of messages related to bug-number. Every message is an association list with the following attributes:

msg_num

The number of the message inside the bug log. The numbers are ascending, newer messages have a higher number.

header

The header lines from the E-mail messages, as arrived at the bug tracker.

body

The message body.

attachments

A list of possible attachments, or nil. Not implemented yet server side.

Function: debbugs-get-message-numbers messages ¶

Returns the message numbers of messages. messages must be the result of a debbugs-get-bug-log call.

Example. Get message numbers from bug report #456789 log from Debian BTS:

(let ((debbugs-port "debian.org"))
   (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))

⇒ (5 10 12)

Function: debbugs-get-message messages message-number ¶

Returns the message message-number of messages. messages must be the result of a 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 message-number, the function returns nil.

Example: Return the first message of the last submitted bug report to GNU BTS:

(let* ((debbugs-port "gnu.org")
       (messages (apply 'debbugs-get-bug-log
			(debbugs-newest-bugs 1))))
  (debbugs-get-message
   messages
   (car (debbugs-get-message-numbers messages))))

Function: debbugs-get-mbox bug-number mbox-type &optional filename ¶

Download mbox with all messages from bug report bug-number. mbox-type specifies a type of mbox and can be one of the following symbols:

mboxfolder

Download mbox folder, i.e. mbox with messages as they arrived at the Debbugs server.

mboxmaint

Download maintainer’s mbox, i.e. mbox with messages as they are resent from the Debbugs server.

mboxstat

mboxstatus

Download status mbox. The use of either symbol depends on the actual Debbugs server configuration. For "gnu.org", use the former; for "debian.org" - the latter.

filename, if non-nil, is the name of the file to store mbox. If filename is nil, the downloaded mbox is inserted into the current buffer.

Note, that mbox downloading will work only if the :bugreport-url field of the debbugs-servers user option is specified (see Configuration).

7 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 "gnu.org" uses also package names as user identification.

Function: debbugs-get-usertag &rest query ¶

Return a list of bug numbers which match query.

query is a sequence of keyword-value pairs where the values are strings, i.e. :KEYWORD “VALUE” [:KEYWORD “VALUE”]*

Valid keywords are:

:user

The value is the name of the package a bug belongs to, like "emacs", "coreutils", or "tramp". It can also be an email address of a user who has applied a user tag. The special email address "me" is used as pattern, replaced with user-mail-address. There must be at least one such entry; it is recommended to have exactly one.

:tag

A string applied as user tag. Often, it is a subproduct identification, like "cedet" or "tramp" for the package "emacs".

If there is no :tag entry, no bug numbers will be returned but a list of existing user tags for :user.

Example. Get all user tags for the package "emacs":

(let ((debbugs-port "gnu.org"))
  (debbugs-get-usertag :user "emacs"))

⇒ ("www" "solaris" "ls-lisp" "cygwin")

Get all bugs tagged by package "emacs" with "www" or "cygwin")):

(let ((debbugs-port "gnu.org"))
  (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))

⇒ (807 1223 5637)