This is docYEMY4y.info, produced by makeinfo version 6.8 from
debbugs.texi.

Copyright (C) 2011-2025 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.
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* Debbugs: (debbugs).  A library for communication with Debbugs.
END-INFO-DIR-ENTRY


File: docYEMY4y.info,  Node: Top,  Next: Installation,  Up: (dir)

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 *note Debbugs User Guide: (debbugs-ug)Top.

* Menu:

* Installation::                Getting and installing 'debbugs'.
* Configuration::               Configuring 'debbugs'.
* Requesting bug numbers::      How to request bug report numbers.
* Requesting bugs statuses::    How to request the status of bug reports.
* Searching bugs::              How to search for bugs.
* Requesting messages::         How to get messages from bug reports.
* Requesting user tags::        How to request tags set by users.


File: docYEMY4y.info,  Node: Installation,  Next: Configuration,  Prev: Top,  Up: Top

1 Installation
**************

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

Install 'debbugs' from the *note ELPA repository: (elisp)Packaging.

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
(https://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
(https://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.


File: docYEMY4y.info,  Node: Configuration,  Next: Requesting bug numbers,  Prev: Installation,  Up: Top

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' (*note 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.


File: docYEMY4y.info,  Node: Requesting bug numbers,  Next: Requesting bugs statuses,  Prev: Configuration,  Up: Top

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' (*note (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)


File: docYEMY4y.info,  Node: Requesting bugs statuses,  Next: Searching bugs,  Prev: Requesting bug numbers,  Up: Top

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' (*note 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'
          (*note 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' (*note 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>"


File: docYEMY4y.info,  Node: Searching bugs,  Next: Requesting messages,  Prev: Requesting bugs statuses,  Up: Top

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://dbmx.net/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")))


File: docYEMY4y.info,  Node: Requesting messages,  Next: Requesting user tags,  Prev: Searching bugs,  Up: Top

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 (*note
     Configuration::).


File: docYEMY4y.info,  Node: Requesting user tags,  Prev: Requesting messages,  Up: Top

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)



Tag Table:
Node: Top1091
Node: Installation3235
Node: Configuration4338
Node: Requesting bug numbers6850
Node: Requesting bugs statuses12208
Node: Searching bugs16492
Node: Requesting messages23274
Node: Requesting user tags26287

End Tag Table


Local Variables:
coding: utf-8
End:
