code.delx.au - gnu-emacs-elpa/blob - packages/debbugs/debbugs.info

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