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

   1 This is debbugs-ug.info, produced by makeinfo version 6.1 from
   2 debbugs-ug.texi.
   3
   4 Copyright (C) 2015-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 UG: (debbugs-ug).  Debbugs User Interface in Emacs.
  25 END-INFO-DIR-ENTRY
  26
  27 \1f
  28 File: debbugs-ug.info,  Node: Top,  Next: Retrieving Bugs,  Up: (dir)
  29
  30 Debbugs User Guide
  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 email addresses.  However,
  39 searching the bug reports, querying bug report status and viewing
  40 comments have been web-based for a long time.  To overcome this
  41 inconvenience the Debbugs/SOAP service was introduced.
  42
  43    Based on the Debbugs/SOAP service, frontends are written which
  44 offer handling of bugs inside Emacs.  These frontends are restricted
  45 to the GNU Debbugs server.  Bugs are presented either as tabulated
  46 list ('debbugs-gnu') or as 'org-mode' TODO list ('debbugs-org', *note
  47 Org Mode: (org)Top.).  As backend they use the 'debbugs' Emacs library
  48 (*note Debbugs Programmer's Manual: (debbugs)Top.).
  49
  50 * Menu:
  51
  52 * Retrieving Bugs::             How to retrieve bugs.
  53 * Searching Bugs::              How to search in the debbugs database.
  54 * Layout::                      How the results are presented.
  55 * Minor Mode::                  How to use browse bug URLs.
  56
  57 * Command Index::               Debbugs commands.
  58 * Variable Index::              User options and variables.
  59 * Key Index::                   Keyboard strokes on bug report buffers.
  60
  61 \1f
  62 File: debbugs-ug.info,  Node: Retrieving Bugs,  Next: Searching Bugs,  Prev: Top,  Up: Top
  63
  64 1 Retrieving Bugs
  65 *****************
  66
  67 Bugs are retrieved by the 'debbugs-gnu' or 'debbugs-org' commands.  In
  68 their simple version, they retrieve just bugs for the '"emacs"'
  69 package on the GNU Debbugs server, filtered by bug severities.
  70 Further filtering is possible when the commands are called with a
  71 prefix.
  72
  73    When the bug numbers to be retrieved are known, the commands
  74 'debbugs-gnu-bugs' or 'debbugs-org-bugs' are applicable.
  75
  76  -- Command: debbugs-gnu severities &optional packages archivedp
  77           suppress tags
  78  -- Command: debbugs-org severities &optional packages archivedp
  79           suppress tags
  80
  81      These commands retrieve bug reports from the GNU Debbugs server.
  82      'debbugs-gnu' returns a tabulated list, and 'debbugs-org' returns
  83      a list of TODO items in 'org-mode'.  In order not to stress the
  84      GNU Debbugs server, the bugs are retrieved in chunks of 500 bugs.
  85      However, the bug report buffer shows all retrieved bugs then, in
  86      reverse bug number order.
  87
  88      SEVERITIES is a list of strings which filter for the severities
  89      of the bugs to be retrieved.  Valid severities are '"serious"',
  90      '"important"', '"normal"', '"minor"' and '"wishlist"' (see also
  91      the constant 'debbugs-gnu-all-severities').  If the list is
  92      empty, there is no filtering with respect to severities.  The
  93      keyword '"tagged"', which is also possible, is not a severity in
  94      the GNU Debbugs server but allows to restrict the result to bugs
  95      with a given user tag.
  96
  97      PACKAGES, also a list of strings, point to the defined software
  98      packages on the GNU Debbugs server which shall be taken into
  99      account.  The existing package names are compiled into the
 100      constant 'debbugs-gnu-all-packages'.
 101
 102      ARCHIVEDP, if non-'nil', extends the result also on archived bugs
 103      on the GNU Debbugs server.
 104
 105      SUPPRESS shall also distinct between 'nil' and non-'nil'.  When
 106      non-'nil', closed bugs are suppressed from being retrieved from
 107      the Debbugs server.  Which bugs are regarded as suppressed is
 108      configured in the customer option 'debbugs-gnu-suppress-bugs'.
 109      Per default, bugs marked as '"done"' are suppressed from being
 110      retrieved.
 111
 112      When SEVERITIES contains the severity '"tagged"', TAGS is
 113      consulted in order to restrict the result on bugs which are
 114      tagged with one of the strings of the list TAGS.  This list can
 115      also be empty; in this case locally tagged bugs are included into
 116      the results.
 117
 118      Called interactively, the commands require just the SEVERITIES
 119      and the TAGS (if SEVERITIES includes '"tagged"').  In order to
 120      provide the other arguments interactively, the commands must be
 121      called with a prefix, like 'C-u M-x debbugs-gnu'.  In the
 122      minibuffer, lists must be entered comma-separated.
 123
 124      Default values for interactive use could be configured in the
 125      customer options 'debbugs-gnu-default-severities' and
 126      'debbugs-gnu-default-packages'.
 127
 128      *note Layout:: for the presentation of the results.
 129
 130  -- Command: debbugs-gnu-bugs &rest bugs
 131  -- Command: debbugs-org-bugs &rest bugs
 132
 133      The commands 'debbugs-gnu-bugs' and 'debbugs-org-bugs' show bugs
 134      specified by their bug number.  Interactively, the bug numbers
 135      must be entered as comma-separated list.
 136
 137      *note Layout:: for the presentation of the results.
 138
 139  -- Command: debbugs-gnu-patches
 140  -- Command: debbugs-org-patches
 141
 142      The commands 'debbugs-gnu-patches' and 'debbugs-org-patches' show
 143      all bugs tagged with '"patch"'.  This is useful for bug triages.
 144
 145      *note Layout:: for the presentation of the results.
 146
 147 \1f
 148 File: debbugs-ug.info,  Node: Searching Bugs,  Next: Layout,  Prev: Retrieving Bugs,  Up: Top
 149
 150 2 Searching in the Debbugs Database.
 151 ************************************
 152
 153 The GNU Debbugs server allows text search in the database in the
 154 messages submitted to the bugs.  It uses a HyperEstraier based search
 155 engine
 156 (http://fallabs.com/hyperestraier/uguide-en.html#searchcond)(1).
 157
 158  -- Command: debbugs-gnu-search
 159  -- Command: debbugs-org-search
 160
 161      These both commands are completely interactive.  They ask for a
 162      '"search phrase"' for the text search.  It is just a string which
 163      contains the words to be searched for, combined by operators like
 164      AND, ANDNOT and OR.  If there is no operator between the words,
 165      AND is used by default.  Only complete words, contained in a
 166      message body, are searched for.
 167
 168      Wild card searches are also supported.  It can be used for
 169      forward match search and backward match search.  For example,
 170      "[BW] euro" matches words which begin with "euro".  "[EW] sphere"
 171      matches words which end with "sphere".  Moreover, regular
 172      expressions are also supported.  For example, "[RX] ^inter.*al$"
 173      matches words which begin with "inter" and end with "al".(2)
 174
 175      While the words to be searched for are case insensitive, the
 176      operators must be specified case sensitive.
 177
 178      While the search for the phrase is performed only in the bodies
 179      of the messages belonging to a bug report, it is also possible to
 180      discriminate the search to further bug attributes.  The commands
 181      ask for such key-value pairs, until an empty key is returned.
 182      Possible attributes are
 183
 184      'severity'
 185           A comma-separated list of bug severities, *Note Retrieving
 186           Bugs::.
 187
 188      'package'
 189           A comma-separated list of defined software packages on the
 190           GNU Debbugs server, *Note Retrieving Bugs::.
 191
 192      'tags'
 193           A comma-separated list of defined user tags.
 194
 195      'author'
 196           The email address of a message originator.
 197
 198      'date'
 199           A time period the bug has been in which the bug has been
 200           submitted or modified.
 201
 202      'subject'
 203           Word(s) the subject of the bug report contains.
 204
 205      'status'
 206           The status of the bug report.  Valid values are "open",
 207           "forwarded" and "done".
 208
 209      It is also possible to apply these commands with an empty search
 210      phrase.  In this case, the GNU Debbugs server is searched only
 211      for bugs which fulfill the given attributes.  The attributes to
 212      be applied are the same as already described, plus
 213
 214      'archive'
 215           Whether archived bugs shall be searched (no value to be
 216           entered).
 217
 218      'src'
 219           Bugs which belong to a given source, if that attribute has
 220           set.
 221
 222      'tag'
 223           An arbitrary string the bug is annotated with.  Usually,
 224           this is the same as the status mentioned above.
 225
 226      'owner'
 227      'submitter'
 228      'maint'
 229      'correspondent'
 230           The email address of the bug's owner, submitter, maintainer,
 231           or correspondent (somebody who has participated in bug
 232           messages).
 233
 234      'log_modified'
 235      'last_modified'
 236      'found_date'
 237      'fixed_date'
 238           The date of the last update, or the date of the bug report /
 239           bug fix.
 240
 241      'unarchived'
 242           The date the bug has been unarchived, if ever.
 243
 244      'done'
 245           The email address of the worker who has closed the bug (if
 246           done).
 247
 248      'forwarded'
 249           A URL or an email address.
 250
 251      'msgid'
 252           The message id of the initial bug report.
 253
 254      'summary'
 255           The summary of the bug report.
 256
 257      Not all of these attributes could be queried on the GNU Debbugs
 258      server via the Debbugs/SOAP backend.  In this case, the results
 259      of a query are discriminated on the client side, which is
 260      indicated by the string "(client-side filter)" in the minibuffer
 261      after the attribute name.  Note, that client side filters perform
 262      badly, because they could be applied only after all bugs have
 263      been downloaded.
 264
 265    ---------- Footnotes ----------
 266
 267    (1) This has been added to the Debbugs/SOAP backend of the GNU
 268 Debbugs server only.
 269
 270    (2) Simplified forms, as described in the Hyperestraier User Guide,
 271 are not supported.
 272
 273 \1f
 274 File: debbugs-ug.info,  Node: Layout,  Next: Minor Mode,  Prev: Searching Bugs,  Up: Top
 275
 276 3 Layout
 277 ********
 278
 279 The commands described in the previous chapters generate (a) report
 280 buffer(s) applicable for navigation.  'debbugs-gnu-*' return a
 281 tabulated list, and 'debbugs-org-*' return a list of TODO items in
 282 'org-mode'.
 283
 284 * Menu:
 285
 286 * Tabulated Lists::             Tabulated Lists.
 287 * TODO Items::                  TODO Items.
 288 * Control Messages::            Control Messages.
 289
 290 \1f
 291 File: debbugs-ug.info,  Node: Tabulated Lists,  Next: TODO Items,  Up: Layout
 292
 293 3.1 Tabulated Lists
 294 ===================
 295
 296 A tabulated list of bug reports consist of four columns for every bug
 297 entry: 'Id' (the bug number), 'State' (some bug attributes),
 298 'Submitter' (the name of the bug submitter), and 'Title' (the bug
 299 subject).  Per default the bugs are sorted descending by 'Id'; this
 300 could be changed by clicking in the headline.
 301
 302    Different foreground colours present further information on the bug
 303 report.  If the bug number uses a red colour ('debbugs-gnu-tagged'),
 304 the bug has been tagged locally.  The same face is used to mark bugs
 305 in the submitter or title column, when the bug has been reported / is
 306 maintained by the user.
 307
 308    The bug state could appear in different colours: red
 309 ('debbugs-gnu-new', nobody has answered yet to this bug), ForestGreen
 310 ('debbugs-gnu-handled', the bug has been modified recently),
 311 MidnightBlue ('debbugs-gnu-pending', the bug is pending), orange
 312 ('debbugs-gnu-stale', the bug has not been touched for a while), and
 313 DarkGrey ('debbugs-gnu-done', the bug is closed).  Archived bugs are
 314 shown with inverse face ('debbugs-gnu-archived').
 315
 316    The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
 317 This enables the following key strokes:
 318
 319 '<RET>'        'debbugs-gnu-select-report'
 320 '<mouse-1>'    Show the email messages that discuss the bug.
 321 '<mouse-2>'
 322
 323 'd'            'debbugs-gnu-display-status'
 324                Show all bug attributes.
 325
 326 '/'            'debbugs-gnu-narrow-to-status'
 327                Narrow the list of bugs to the bugs that match the
 328                given regex in 'State', 'Submitter' or 'Title'.
 329
 330 'R'            'debbugs-gnu-show-all-blocking-reports'
 331                Narrow the list of bug reports to the ones that are
 332                blocking the current release.
 333
 334 'w'            'debbugs-gnu-widen'
 335                Restore the full list again after narrowing.
 336
 337 'g'            'debbugs-gnu-rescan'
 338                Reload all bugs.  With a prefix argument 'C-u', the
 339                bug status cache is disabled, and all bug reports are
 340                retrieved from the GNU Debbugs server.
 341
 342 'B'            'debbugs-gnu-show-blocking-reports'
 343 'b'            'debbugs-gnu-show-blocked-by-reports'
 344                Show all bug reports which are blocking / blocked by
 345                this bug.
 346
 347 's'            'debbugs-gnu-toggle-sort'
 348                Toggle sorting order of bugs.
 349
 350 't'            'debbugs-gnu-toggle-tag'
 351                Toggle local tag of bugs.
 352
 353 'x'            'debbugs-gnu-toggle-suppress'
 354                Toggle showing of closed bugs.
 355
 356 'C'            'debbugs-gnu-send-control-message'
 357                Send a control message for this bug,
 358                *note Control Messages::.
 359
 360
 361    The user option 'debbugs-gnu-suppress-closed' controls, whether
 362 closed bugs are shown in the initial list.
 363
 364    The user option 'debbugs-gnu-mail-backend' controls the
 365 presentation of email messages produced by typing '<RET>' or by
 366 clicking the mouse on a bug: if its value is 'gnus', the default, a
 367 GNUS ephemeral group for that bug will be shown; if its value is
 368 'rmail', the command will present an Rmail folder instead.
 369
 370 \1f
 371 File: debbugs-ug.info,  Node: TODO Items,  Next: Control Messages,  Prev: Tabulated Lists,  Up: Layout
 372
 373 3.2 TODO Items
 374 ==============
 375
 376 TODO items are offered as usual in 'org-mode'.  The bug attributes are
 377 mapped onto properties of these items.  They can be shown by the usual
 378 navigation in 'org-mode'.
 379
 380    Bug severities are mapped onto org severities, see
 381 'debbugs-org-severity-priority'.
 382
 383    The bug report buffers have enabled the minor 'debbugs-org-mode'.
 384 This enables the following key strokes:
 385
 386 '<TAB>'     'org-cycle'
 387             Outline the bug report attributes in 'org-mode'.
 388
 389 'C-c # d'   'debbugs-gnu-display-status'
 390             Show all bug attributes.
 391
 392 'C-c # t'   'debbugs-gnu-toggle-tag'
 393             Toggle local tag of bugs.
 394
 395 'C-c # C'   'debbugs-gnu-send-control-message'
 396             Send a control message for this bug, *note Control Messages::.
 397
 398
 399    When the bug attributes are shown by 'org-cycle', there is a link
 400 'Messages' which opens a GNUS ephemeral group for that bug.
 401
 402 \1f
 403 File: debbugs-ug.info,  Node: Control Messages,  Prev: TODO Items,  Up: Layout
 404
 405 3.3 Control Messages
 406 ====================
 407
 408 Debbugs control messages are sent by email to the GNU Debbugs control
 409 server.  Their format is described in
 410 <http://debbugs.gnu.org/server-control.html>.
 411
 412    A control message can be initiated in the tabulated list of bugs,
 413 in the list of org TODO items, or in the GNUS ephemeral group or Rmail
 414 folder opened for the messages belonging to a given bug.  Control
 415 messages can be sent to unarchived bugs only, in case a bug is
 416 archived the control message 'unarchive' must be sent first.
 417
 418    In the minibuffer, the following control messages can be requested
 419 (assuming that 12345 is the bug the control message is intended for).
 420 The strings show the exact format of the control messages.
 421
 422 'block'
 423 'unblock'
 424      "block|unblock 12345 by 54321"
 425
 426      The second bug number is read interactively.  It could be also a
 427      list of comma-separated bug numbers.
 428
 429 'close'
 430      "close 12345 25.1"
 431
 432      The second argument, the Emacs version, is read interactively.
 433
 434 'confirmed'
 435 'fixed'
 436 'help'
 437 'moreinfo'
 438 'notabug'
 439 'patch'
 440 'pending'
 441 'security'
 442 'unreproducible'
 443 'wontfix'
 444      "tags 12345 confirmed|fixed|help|moreinfo|notabug"
 445
 446      "tags 12345 patch|pending|security|unreproducible|wontfix"
 447
 448 'done'
 449 'donenotabug'
 450 'doneunreproducible'
 451 'donewontfix'
 452      "tags 12345 fixed|notabug|unreproducible|wontfix"
 453      "close 12345 25.1"
 454
 455      The second argument in the close message, the Emacs version, is
 456      read interactively.
 457
 458 'forcemerge'
 459 'merge'
 460      "forcemerge|merge 12345 54321"
 461
 462      The second bug number is read interactively.
 463
 464 'invalid'
 465      "tags 12345 notabug"
 466      "tags 12345 wontfix"
 467      "close 12345"
 468
 469 'noowner'
 470      "noowner 12345"
 471
 472 'owner'
 473      "owner 12345 !"
 474
 475 'reassign'
 476      "reassign 12345 PACKAGE"
 477
 478      The package name on the GNU Debbugs server is read interactively.
 479
 480 'reopen'
 481      "reopen 12345"
 482
 483 'retitle'
 484      "retitle 12345 TITLE"
 485
 486      The new bug title is read interactively.
 487
 488 'serious'
 489 'important'
 490 'normal'
 491 'minor'
 492 'wishlist'
 493      "severity 12345 serious|important|normal|minor|wishlist"
 494
 495 'unarchive'
 496      "unarchive 12345"
 497
 498 'unmerge'
 499      "unmerge 12345"
 500
 501 'usertag'
 502      "user USERNAME"
 503      "usertag 12345 TAG"
 504
 505      The username, read interactively, is either a package name or an
 506      email address.  The tag to be set is also read interactively.
 507
 508 \1f
 509 File: debbugs-ug.info,  Node: Minor Mode,  Next: Command Index,  Prev: Layout,  Up: Top
 510
 511 4 Minor Mode
 512 ************
 513
 514 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
 515 like 'ChangeLog', or in commentary sections of other files.  The
 516 reference to such bugs have a specialized format, <Bug#12345>.  The
 517 hyperlinks are implemented as minor modes 'bug-reference-mode' and
 518 'bug-reference-prog-mode'.
 519
 520    This package adds a new minor mode 'debbugs-browse-mode' on top of
 521 them.  Instead of using the default built-in Emacs browser for a given
 522 bug reference, it opens a corresponding bug report buffer.  The
 523 customer option 'debbugs-browse-function' controls, whether
 524 'debbugs-gnu-bugs' or 'debbugs-org-bugs' is called.
 525
 526    This minor mode is applicable for all URLs, not only bug
 527 references.  Any URL with the format <http://debbugs.gnu.org/12345>
 528 will be shown in a bug report buffer, when 'debbugs-browse-mode' is
 529 enabled.
 530
 531 \1f
 532 File: debbugs-ug.info,  Node: Command Index,  Next: Variable Index,  Prev: Minor Mode,  Up: Top
 533
 534 Command Index
 535 *************
 536
 537