packages/debbugs/debbugs.texi

   1 \input texinfo
   2 @setfilename debbugs.info
   3 @settitle Debbugs programmer's manual
   4
   5 @dircategory Emacs
   6 @direntry
   7 * Debbugs: (debbugs).  A library for communication with Debbugs.
   8 @end direntry
   9
  10 @copying
  11 Copyright @copyright{} 2011 Free Software Foundation, Inc.
  12
  13 @quotation
  14 Permission is granted to copy, distribute and/or modify this document
  15 under the terms of the GNU Free Documentation License, Version 1.2 or
  16 any later version published by the Free Software Foundation; with no
  17 Invariant Sections, with the Front-Cover, or Back-Cover Texts.  A copy of
  18 the license is included in the section entitled ``GNU Free Documentation
  19 License'' in the Emacs manual.
  20
  21 This document is part of a collection distributed under the GNU Free
  22 Documentation License.  If you want to distribute this document
  23 separately from the collection, you can do so by adding a copy of the
  24 license to the document, as described in section 6 of the license.
  25
  26 All Emacs Lisp code contained in this document may be used, distributed,
  27 and modified without restriction.
  28 @end quotation
  29 @end copying
  30
  31 @titlepage
  32 @title Debbugs Programmer's Manual
  33 @author by Evgeny M. Zubok
  34 @page
  35 @insertcopying
  36 @end titlepage
  37
  38 @contents
  39
  40 @node Top
  41 @top Debbugs Programmer's Manual
  42
  43 Debbugs is a bugtracking system (BTS) that was initially written for
  44 the Debian project but actually used also by the GNU project.  The
  45 main distinctive feature of Debbugs is that it's mostly email-based.
  46 All actions on bug reports: opening, closing, changing the status,
  47 commenting, forwarding are performed via email by sending specially
  48 composed letters to the particular mail addresses.  However, searching
  49 the bug reports, querying bug report status and viewing comments have
  50 been web-based for a long time.  To overcome this inconvenience the
  51 Debbugs/SOAP service was introduced.
  52
  53 The Debbugs/SOAP service provides the means for developers to write
  54 client applications that can send the queries with certain search
  55 criteria to the Debbugs server and retrieve a set of bug reports that
  56 match them.  The developer may also ask the Debbugs server for
  57 additional information about every bug report (e.g. subject, date,
  58 originator, tags and etc.) and get all comments and attachments.
  59
  60 @code{debbugs}, described in this document, is the Emacs library that
  61 exposes to developers the available functions provided by the Debbugs
  62 server.  @code{debbugs} uses Emacs' SOAP client library for
  63 communication with the Debbugs server.  In tandem with Emacs' email
  64 facilities, @code{debbugs} provides a solution for building
  65 applications that interact with the Debbugs BTS directly from Emacs
  66 without addressing Debbugs' web interface.
  67
  68 @menu
  69 * Installation::                Getting and installing @code{debbugs}.
  70 * Configuration::               Configuring @code{debbugs}.
  71 * Requesting bug numbers::      How to request bug report numbers.
  72 * Requesting bugs statuses::    How to request the status of bug reports.
  73 * Requesting messages::         How to get messages from bug reports.
  74 * Requesting user tags::        How to request tags set by users.
  75 @end menu
  76
  77 @node Installation
  78 @chapter Installation
  79
  80 @subheading Installation on Emacs 24 or later
  81
  82 Install @code{debbugs} from the @ref{Packaging, ELPA repository, , elisp}.
  83
  84 @subheading Installation on Emacs 22 and Emacs 23
  85
  86 If you want to install @code{debbugs} on Emacs 22/23, you will need to
  87 install the @code{soap-client} library first.  It can be downloaded from
  88 the @uref{http://code.google.com/p/emacs-soap-client/, Emacs SOAP client
  89 project page}.
  90
  91 Compile the library and add it into your @code{load-path}:
  92
  93 @example
  94 (add-to-list 'load-path "/path/to/emacs-soap-client/")
  95 @end example
  96
  97 @code{debbugs} library can be downloaded from the
  98 @uref{http://elpa.gnu.org/packages/, ELPA repository}.  Compile it and
  99 set the @code{load-path}:
 100
 101 @example
 102 (add-to-list 'load-path "/path/to/debbugs/")
 103 @end example
 104
 105 @subheading Installation on Emacs 21
 106
 107 We have not tried yet to install @code{debbugs} on Emacs 21.  We would
 108 definitely say that the installation will require even more additional
 109 libraries than needed for installation on Emacs 22/23.
 110
 111 @node Configuration
 112 @chapter Configuration
 113
 114 @code{debbugs} is already configured to work with two main ports of
 115 Debbugs BTS: @uref{http://bugs.debian.org} and
 116 @uref{http://debbugs.gnu.org}.  So if you intend to use one of these
 117 ports, you don't need to configure @code{debbugs}.  If you want to
 118 interact with a Debbugs port other than those listed, you have to
 119 configure @code{debbugs} by adding a new server specifier to the
 120 @code{debbugs-servers} variable.  The actual port can be selected by
 121 the @code{debbugs-port} variable.
 122
 123 @defvar debbugs-servers
 124 List of Debbugs server specifiers.  Each entry is a list that contains a
 125 string identifying the port name and the server parameters in
 126 keyword-value form.  The list initially contains two predefined and
 127 configured Debbugs servers: @code{"gnu.org"} and @code{"debian.org"}.
 128
 129 Valid keywords are:
 130
 131 @table @code
 132 @item :wsdl
 133 Location of WSDL.  The value is a string with the URL that should
 134 return the WSDL specification of the Debbugs/SOAP service.  This
 135 keyword is intended for future use, it is ignored currently.
 136
 137 @item :bugreport-url
 138 The URL of the server script (@code{bugreport.cgi} in the default
 139 Debbugs installation) that provides the access to mboxes with messages
 140 from bug reports.
 141 @end table
 142
 143 Example.  Add a new Debbugs port with name "foobars.net":
 144
 145 @example
 146 (add-to-list
 147  'debbugs-servers
 148  '("foobars.net"
 149    :wsdl "http://bugs.foobars.net/cgi/soap.cgi?WSDL"
 150    :bugreport-url "http://bugs.foobars.net/cgi/bugreport.cgi"))
 151 @end example
 152 @end defvar
 153
 154 @defvar debbugs-port
 155 This variable holds the name of the currently used port.  The value of
 156 the variable corresponds to the Debbugs server to be accessed, either
 157 @code{"gnu.org"} or @code{"debian.org"}, or a user defined port name.
 158 @end defvar
 159
 160 @node Requesting bug numbers
 161 @chapter Requesting bug numbers
 162
 163 In Debbugs BTS, the bug number is the unique identifier of a bug
 164 report.  The functions described in this section return from the
 165 Debbugs server the list of bug numbers that match a user's query.
 166
 167 @defun debbugs-get-bugs &rest query
 168 This function returns a list of bug numbers that match the
 169 @var{query}. @var{query} is a sequence of keyword-value pairs where the
 170 values are strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
 171
 172 The keyword-value pair is a subquery.  The keywords are allowed to
 173 have multiple occurrence within the query at any place.  The
 174 subqueries with the same keyword form the logical subquery, which
 175 returns the union of bugs of every subquery it contains.
 176
 177 The result of the @var{query} is an intersection of results of all
 178 subqueries.
 179
 180 Valid keywords are:
 181
 182 @table @code
 183 @item :package
 184 The value is the name of the package a bug belongs to, like @code{"emacs"},
 185 @code{"coreutils"}, @code{"gnus"}, or @code{"tramp"}.
 186
 187 @item :src
 188 This is used to retrieve bugs that belong to source with given name.
 189
 190 @item :severity
 191 This is the severity of the bug.  The exact set of available severities
 192 depends on the policy of a particular Debbugs port:
 193
 194 Debian port:
 195 @code{"critical"}, @code{"grave"}, @code{"serious"},
 196 @code{"important"}, @code{"normal"}, @code{"minor"}, @code{"wishlist"},
 197 and @code{"fixed"}.
 198
 199 GNU port:
 200 @code{"serious"}, @code{"important"}, @code{"normal"}, @code{"minor"},
 201 @code{"wishlist"}.
 202
 203 @item :tag
 204 An arbitrary string the bug is annotated with.  Usually, this is used
 205 to mark the status of the bug.  The list of possible tags depends on
 206 the Debbugs port.
 207
 208 Debian port: @code{"patch"}, @code{"wontfix"}, @code{"moreinfo"},
 209 @code{"unreproducible"}, @code{"fixed"}, @code{"potato"},
 210 @code{"woody"}, @code{"sid"}, @code{"help"}, @code{"security"},
 211 @code{"upstream"}, @code{"pending"}, @code{"sarge"},
 212 @code{"sarge-ignore"}, @code{"experimental"}, @code{"d-i"},
 213 @code{"confirmed"}, @code{"ipv6"}, @code{"lfs"},
 214 @code{"fixed-in-experimental"}, @code{"fixed-upstream"}, @code{"l10n"},
 215 @code{"etch"}, @code{"etch-ignore"}, @code{"lenny"},
 216 @code{"lenny-ignore"}, @code{"squeeze"}, @code{"squeeze-ignore"},
 217 @code{"wheezy"}, @code{"wheezy-ignore"}. The actual list of tags can be
 218 found on @uref{http://www.debian.org/Bugs/Developer#tags}.
 219
 220 GNU port: @code{"fixed"}, @code{"notabug"}, @code{"wontfix"},
 221 @code{"unreproducible"}, @code{"moreinfo"}, @code{"patch"},
 222 @code{"pending"}, @code{"help"}, @code{"security"}, @code{"confirmed"}.
 223 See @url{http://debbugs.gnu.org/Developer.html#tags} for the actual list
 224 of tags.
 225
 226 @item :owner
 227 This is used to identify bugs by the owner's email address.  The
 228 special email address @code{"me"} is used as pattern, replaced with
 229 the variable @code{user-mail-address} (@pxref{(elisp)User
 230 Identification}).
 231
 232 @item :submitter
 233 With this keyword it is possible to filter bugs by the submitter's
 234 email address.  The special email address @code{"me"} is used as
 235 pattern, replaced with the variable @code{user-mail-address}.
 236
 237 @item :maint
 238 This is used to find bugs of the packages which are maintained by the
 239 person with the given email address.  The special email address
 240 @code{"me"} is used as pattern, replaced with @code{user-mail-address}.
 241
 242 @item :correspondent
 243 This allows to find bug reports where the person with the given email
 244 address has participated.  The special email address @code{"me"} is used
 245 as pattern, replaced with @code{user-mail-address}.
 246
 247 @item :affects
 248 With this keyword it is possible to find bugs which affect the package
 249 with the given name.  The bugs are chosen by the value of field
 250 @code{affects} in bug's status.  The returned bugs do not necessary
 251 belong to this package.
 252
 253 @item :status
 254 Status of bug.  Valid values are @code{"done"}, @code{"forwarded"} and
 255 @code{"open"}.
 256
 257 @item :archive
 258 A keyword to filter for bugs which are already archived, or not.  Valid
 259 values are @code{"0"} (not archived), @code{"1"} (archived) or
 260 @code{"both"}.  If this keyword is not given in the query,
 261 @code{:archive "0"} is assumed by default.
 262 @end table
 263
 264 Example.  Get all opened and forwarded release critical bugs for the
 265 packages which are maintained by @code{"me"} and which have a patch:
 266
 267 @example
 268 (let ((debbugs-port "debian.org"))
 269   (debbugs-get-bugs :maint "me" :tag "patch"
 270                     :severity "critical"
 271                     :status "open"
 272                     :severity "grave"
 273                     :status "forwarded"
 274                     :severity "serious"))
 275 @end example
 276 @end defun
 277
 278 @defun debbugs-newest-bugs amount
 279 This function returns a list of bug numbers, according to @var{amount}
 280 (a number) of latest bugs.
 281
 282 Example.  Get the latest six bug report numbers from Debian BTS:
 283
 284 @example
 285 (let ((debbugs-port "debian.org"))
 286   (debbugs-newest-bugs 6))
 287 @result{} (633152 633153 633154 633155 633156 633157)
 288 @end example
 289 @end defun
 290
 291 @node Requesting bugs statuses
 292 @chapter Requesting bugs statuses
 293
 294 Bug status is a collection of fields that holds the information about
 295 the state and importance of the bug report, about originator, owner and
 296 various aspects of relationship with other bug reports.
 297
 298 @defun debbugs-get-status &rest bug-numbers
 299 Return a list of status entries for the bug reports identified by
 300 @var{bug-numbers}.  Every returned entry is an association list with the
 301 following attributes:
 302
 303 @table @code
 304 @item id
 305 @itemx bug_num
 306 The bug number.
 307
 308 @item package
 309 A list of package names the bug belongs to.
 310
 311 @item severity
 312 The severity of the bug report.  Possible values are the same as for
 313 @code{:severity} in @code{debbugs-get-bugs} (@pxref{Requesting bug
 314 numbers}).
 315
 316 @item tags
 317 The status of the bug report, a list of strings.  Possible values are the
 318 same as for @code{:tags} in @code{debbugs-get-bugs} (@pxref{Requesting
 319 bug numbers}).
 320
 321 @item pending
 322 The string @code{"pending"}, @code{"forwarded"} or @code{"done"}.
 323
 324 @item subject
 325 Subject/Title of the bugreport.
 326
 327 @item originator
 328 The E-mail address of the bug report submitter.
 329
 330 @item mergedwith
 331 A list of bug numbers this bug was merged with.
 332
 333 @item source
 334 Source package name of the bug report.
 335
 336 @item date
 337 Date of bug creation.  Encoded as UNIX time.
 338
 339 @item log_modified
 340 @itemx last_modified
 341 Date of last update.  Encoded as UNIX time.
 342
 343 @item found_date
 344 @itemx fixed_date
 345 Date of bug report / bug fix (empty for now).  Encoded as UNIX time.
 346
 347 @item done
 348 The E-mail address of the worker who has closed the bug (if done).
 349
 350 @item archived
 351 @code{t} if the bug is archived, @code{nil} otherwise.
 352
 353 @item unarchived
 354 The date the bug has been unarchived, if ever.  Encoded as UNIX time.
 355
 356 @item found_versions
 357 @itemx fixed_versions
 358 List of version strings.
 359
 360 @item forwarded
 361 A URL or an E-mail address.
 362
 363 @item blocks
 364 A list of bug numbers this bug blocks.
 365
 366 @item blockedby
 367 A list of bug numbers this bug is blocked by.
 368
 369 @item msgid
 370 The message id of the initial bug report.
 371
 372 @item owner
 373 Who is responsible for fixing.
 374
 375 @item location
 376 Always the string @code{"db-h"} or @code{"archive"}.
 377
 378 @item affects
 379 A list of package names.
 380
 381 @item summary
 382 Arbitrary text.
 383 @end table
 384
 385 Example.  Get the status of bug number #10 from GNU BTS:
 386
 387 @example
 388 (let ((debbugs-port "gnu.org"))
 389   (debbugs-get-status 10))
 390 @result{}
 391 (((source . "unknown") (found_versions) (done) (blocks)
 392   (date . 1203606305.0) (fixed) (fixed_versions) (mergedwith)
 393   (found) (unarchived) (blockedby) (keywords) (summary)
 394   (msgid . "<87zltuz7eh.fsf@@freemail.hu>") (id . 10)
 395   (forwarded) (severity . "wishlist")
 396   (owner . "Magnus Henoch <*****@@freemail.hu>")
 397   (log_modified . 1310061242.0) (location . "db-h")
 398   (subject . "url-gw should support HTTP CONNECT proxies")
 399   (originator . "Magnus Henoch <*****@@freemail.hu>")
 400   (last_modified . 1310061242.0) (pending . "pending") (affects)
 401   (archived) (tags) (fixed_date) (package "emacs") (found_date)
 402   (bug_num . 10)))
 403 @end example
 404 @end defun
 405
 406 @defun debbugs-get-attribute bug-or-message attribute
 407 General accessor that returns the value of key @var{attribute}.
 408 @var{bug-or-message} must be a list element returned by either
 409 @code{debbugs-get-status} or @code{debbugs-get-bug-log}
 410 (@pxref{Requesting messages}).
 411
 412 Example.  Return the originator of the last submitted bug report:
 413
 414 @example
 415 (let ((debbags-port "gnu.org"))
 416   (debbugs-get-attribute
 417    (car (apply 'debbugs-get-status (debbugs-newest-bugs 1)))
 418    'originator))
 419 @result{} "Jack Daniels <jack@@daniels.com>"
 420 @end example
 421 @end defun
 422
 423 @node Requesting messages
 424 @chapter Requesting messages
 425
 426 @defun debbugs-get-bug-log bug-number
 427 Returns a list of messages related to @var{bug-number}.  Every message is
 428 an association list with the following attributes:
 429
 430 @table @code
 431 @item msg_num
 432 The number of the message inside the bug log.  The numbers are ascending,
 433 newer messages have a higher number.
 434 @item header
 435 The header lines from the E-mail messages, as arrived at the bug
 436 tracker.
 437 @item body
 438 The message body.
 439 @item attachments
 440 A list of possible attachments, or @code{nil}.  Not implemented yet server
 441 side.
 442 @end table
 443 @end defun
 444
 445 @defun debbugs-get-message-numbers messages
 446 Returns the message numbers of @var{messages}.  @var{messages} must be
 447 the result of a @code{debbugs-get-bug-log} call.
 448
 449 Example.  Get message numbers from bug report #456789 log from Debian
 450 BTS:
 451
 452 @example
 453 (let ((debbugs-port "debian.org"))
 454    (debbugs-get-message-numbers (debbugs-get-bug-log 456789)))
 455 @result{} (5 10 12)
 456 @end example
 457 @end defun
 458
 459 @defun debbugs-get-message messages message-number
 460 Returns the message @var{message-number} of
 461 @var{messages}.  @var{messages} must be the result of a
 462 @code{debbugs-get-bug-log} call.  The returned message is a list of
 463 strings.  The first element are the header lines of the message, the
 464 second element is the body of the message.  Further elements of the list,
 465 if any, are attachments of the message.  If there is no message with
 466 @var{message-number}, the function returns @code{nil}.
 467
 468 Example: Return the first message of the last submitted bug report to
 469 GNU BTS:
 470
 471 @example
 472 (let* ((debbugs-port "gnu.org")
 473        (messages (apply 'debbugs-get-bug-log
 474                         (debbugs-newest-bugs 1))))
 475   (debbugs-get-message
 476    messages
 477    (car (debbugs-get-message-numbers messages))))
 478 @end example
 479 @end defun
 480
 481 @defun debbugs-get-mbox bug-number mbox-type &optional filename
 482 Download mbox with all messages from bug report
 483 @var{bug-number}.  @var{mbox-type} specifies a type of mbox and can be
 484 one of the following symbols:
 485
 486 @table @code
 487 @item mboxfolder
 488 Download mbox folder, i.e. mbox with messages as they arrived at the
 489 Debbugs server.
 490
 491 @item mboxmaint
 492 Download maintainer's mbox, i.e. mbox with messages as they are resent
 493 from the Debbugs server.
 494
 495 @item mboxstat
 496 @itemx mboxstatus
 497 Download status mbox.  The use of either symbol depends on the actual
 498 Debbugs server configuration.  For @code{"gnu.org"}, use the former;
 499 for @code{"debian.org} - the latter.
 500 @end table
 501
 502 @var{filename}, if non-@code{nil}, is the name of the file to store
 503 mbox.  If @var{filename} is @code{nil}, the downloaded mbox is
 504 inserted into the current buffer.
 505
 506 Note, that mbox downloading will work only if the
 507 @code{:bugreport-url} field of the @code{debbugs-servers} variable is
 508 specified (@pxref{Configuration}).
 509 @end defun
 510
 511 @node Requesting user tags
 512 @chapter Requesting user tags
 513
 514 A user tag is a string, a user has assigned to one or several bugs.
 515 The user is identified by an email address.  The port @code{"gnu.org"}
 516 uses also package names as user identification.
 517
 518 @defun debbugs-get-usertag &rest query
 519 Return a list of bug numbers which match @var{query}.
 520
 521 @var{query} is a sequence of keyword-value pairs where the values are
 522 strings, i.e. :KEYWORD ``VALUE'' [:KEYWORD ``VALUE'']*
 523
 524 Valid keywords are:
 525
 526 @table @code
 527 @item :user
 528 The value is the name of the package a bug belongs to, like
 529 @code{"emacs"}, @code{"coreutils"}, or @code{"tramp"}.  It can also be
 530 an email address of a user who has applied a user tag.  The special
 531 email address @code{"me"} is used as pattern, replaced with
 532 @code{user-mail-address}.  There must be at least one such entry; it
 533 is recommended to have exactly one.
 534
 535 @item :tag
 536 A string applied as user tag.  Often, it is a subproduct
 537 identification, like @code{"cedet"} or @code{"tramp"} for the package
 538 @code{"emacs"}.
 539 @end table
 540
 541 If there is no @code{:tag} entry, no bug numbers will be returned but
 542 a list of existing user tags for @code{:user}.
 543
 544 Example.  Get all user tags for the package @code{"emacs"}:
 545
 546 @example
 547 (let ((debbugs-port "gnu.org"))
 548   (debbugs-get-usertag :user "emacs"))
 549 @result{} ("www" "solaris" "ls-lisp" "cygwin")
 550 @end example
 551
 552 Get all bugs tagged by package @code{"emacs"} with @code{"www"} or
 553 @code{"cygwin"})):
 554
 555 @example
 556 (let ((debbugs-port "gnu.org"))
 557   (debbugs-get-usertag :user "emacs" :tag "www" :tag "cygwin"))
 558 @result{} (807 1223 5637)
 559 @end example
 560 @end defun
 561
 562 @bye