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

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