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

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