Copyright © 2011-2016 Free Software Foundation, Inc.

     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 the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

     All Emacs Lisp code contained in this document may be used, distributed, and modified without restriction.

Debbugs Programmer's Manual
***************************

Debbugs is a bugtracking system (BTS) that was initially written for the Debian project but currently 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 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 inconvenience the Debbugs/SOAP service was introduced.

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.

debbugs, described in this document, is the Emacs library that exposes to developers the available functions provided by the Debbugs server.  debbugs uses Emacs' SOAP client library for communication with the Debbugs server.  In tandem with Emacs' email facilities, debbugs provides a solution for building applications that interact with the Debbugs BTS directly from Emacs without addressing Debbugs' web interface.

The user interface for accessing the Debbugs server for GNU projects is described in Debbugs User Guide (debbugs-ug).

Installation
************

Installation on Emacs 24 or later
---------------------------------

Install debbugs from the ELPA repository (elisp).

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 (http://code.google.com/p/emacs-soap-client/).

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 (http://elpa.gnu.org/packages/).  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.

Configuration
*************

debbugs is already configured to work with two main ports of Debbugs BTS: http://bugs.debian.org and http://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 variable.  The actual port can be selected by the debbugs-port variable.

 -- Variable: 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 "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
             :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))

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

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". The actual list of tags can be found on http://www.debian.org/Bugs/Developer#tags.

          GNU port: "fixed", "notabug", "wontfix", "unreproducible", "moreinfo", "patch", "pending", "help", "security", "confirmed". See http://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 "done", "forwarded" and "open".

     :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)

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

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

          (let ((debbugs-port "gnu.org"))
            (debbugs-get-status 10))
          =>
          (((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>"

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 variable is specified (see Configuration).

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)