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

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