Allow sending bug control messages from random modes.

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

\input texinfo
@setfilename debbugs.info
@settitle Debbugs programmer's manual

@dircategory Emacs
@direntry
* Debbugs: (debbugs).  A library for communication with Debbugs.
@end direntry

@copying
Copyright @copyright{} 2011 Free Software Foundation, Inc.

@quotation
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.
@end quotation
@end copying

@node Top
@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,
commenting, forwarding are performed via email by sending specially
composed letters to the partucular 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
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.

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

@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.
@end menu

@node Installation
@chapter Installation

@subheading Installation on Emacs 24 or later
Install @code{debbugs} from ELPA repository.

@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
project page}.

Compile the library and add it into your @code{load-path}:

@example
(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}: 

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

@defvar 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: @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.
@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.
@end table

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

@example
(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 example
@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.
@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.

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

Valid keywords are:

@table @code
@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 :severity
This is the severity of the bug. The exact set of available severities
depends on policy of 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"},
@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"},
@code{"unreproducible"}, @code{"fixed"}, @code{"potato"},
@code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
@code{"upstream"}, @code{"pending"}, @code{"sarge"},
@code{"sarge-ignore"}, @code{"experimental"}, @code{"d-i"},
@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"}.

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})
@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}.
@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.
@end table

Example. Get all bug reports that were initiated by me.

@example
(let ((debbugs-port "gnu.org"))
  (debbugs-get-bugs :submitter "me" :archive "both"))
@result{} (5516 5551 5645 7259)
@end example
@end defun

@defun debbugs-newest-bugs amount
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
(let ((debbugs-port "debian.org"))
  (debbugs-newest-bugs 6))
@result{} (633152 633153 633154 633155 633156 633157)
@end example
@end defun

@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
following attributes:

@table @code
@item 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
@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
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.
@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.
@item log_modified
@item 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.
@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.
@item found_versions
@item 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
(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") 
  (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)))
@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}.

Example. Return the originator of last submitted bug report:

@example
(let ((debbags-port "gnu.org"))
  (debbugs-get-attribute
   (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
   'originator))
@result{} "Jack Daniels <jack@@daniels.com>"
@end example
@end defun

@node Requesting messages
@chapter Requesting messages

@defun debbugs-get-bug-log bug-number
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,
newer messages have a higher number.
@item header
The header lines from the E-mail messages, as arrived at the bug
tracker.
@item body
The message body.
@item attachments
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
the result of a @code{debbugs-get-bug-log} call.

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

@example
(let ((debbugs-port "debian.org"))
   (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
@result{} (5 10 12)
@end example
@end defun

@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{message-number}, the function returns @code{nil}.

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

@example
(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))))
@end example
@end defun

@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
one of the following symbols:

@table @code
@item mboxfolder
Download mbox folder, i. e. mbox with messages as they arrived at
Debbugs server.
@item mboxmaint
Download maintainer's mbox, i. e. mbox with messages as they are
resended from 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.
@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.

Note that mbox downloading will work only if the @code{:bugreport-url}
field of @code{debbugs-servers} variable is specified
(@pxref{Configuration}).
@end defun

@bye