Improvement on debbugs

[gnu-emacs-elpa] / packages / debbugs / debbugs.info

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

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

\1f
File: debbugs.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.
* Requesting messages::         How to get messages from bug reports.
* Requesting user tags::        How to request tags set by users.

\1f
File: debbugs.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
(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.

\1f
File: debbugs.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: <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.

\1f
File: debbugs.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"'.  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' (*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 '"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)

\1f
File: debbugs.info,  Node: Requesting bugs statuses,  Next: Requesting messages,  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"' 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' (*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>"

\1f
File: debbugs.info,  Node: Requesting messages,  Next: Requesting user tags,  Prev: Requesting bugs statuses,  Up: Top

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

\1f
File: debbugs.info,  Node: Requesting user tags,  Prev: Requesting messages,  Up: Top

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


\1f
Tag Table:
Node: Top\7f1094
Node: Installation\7f3179
Node: Configuration\7f4278
Node: Requesting bug numbers\7f6190
Node: Requesting bugs statuses\7f11444
Node: Requesting messages\7f15495
Node: Requesting user tags\7f18510
\1f
End Tag Table