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

   1 This is debbugs-ug.info, produced by makeinfo version 5.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).
 303
 304    The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
 305 This enables the following key strokes:
 306
 307 '<RET>'       'debbugs-gnu-select-report'
 308 '<mouse-1>'   Open a GNUS ephemeral group for that bug.
 309 '<mouse-2>'
 310
 311 'd'           'debbugs-gnu-display-status'
 312               Show all bug attributes.
 313
 314 'g'           'debbugs-gnu-rescan'
 315               Reload all bugs from the GNU Debbugs server.
 316
 317 'B'           'debbugs-gnu-show-blocking-reports'
 318 'b'           'debbugs-gnu-show-blocked-by-reports'
 319               Show all bug reports which are blocking / blocked by this bug.
 320
 321 's'           'debbugs-gnu-toggle-sort'
 322               Toggle sorting order of bugs.
 323
 324 't'           'debbugs-gnu-toggle-tag'
 325               Toggle local tag of bugs.
 326
 327 'x'           'debbugs-gnu-toggle-suppress'
 328               Toggle showing of closed bugs.
 329
 330 'C'           'debbugs-gnu-send-control-message'
 331               Send a control message for this bug, *note Control Messages::.
 332
 333
 334 \1f
 335 File: debbugs-ug.info,  Node: TODO Items,  Next: Control Messages,  Prev: Tabulated Lists,  Up: Layout
 336
 337 3.2 TODO Items
 338 ==============
 339
 340 TODO items are offered as usual in 'org-mode'.  The bug attributes are
 341 mapped onto properties of these items.  They can be shown by the usual
 342 navigation in 'org-mode'.
 343
 344    Per bug retrieval only up to 500
 345 ('debbugs-gnu-default-hits-per-page') bugs are retrieved and presented
 346 in a buffer.  At the end of the buffer there is a link, which allows to
 347 append the next 500 bugs to the list.
 348
 349    Bug severities are mapped onto org severities, see
 350 'debbugs-org-severity-priority'.
 351
 352    The bug report buffers have enabled the minor 'debbugs-gnu-mode'.
 353 This enables the following key strokes:
 354
 355 '<TAB>'     'org-cycle'
 356             Outline the bug report attributes in 'org-mode'.
 357
 358 'C-c # d'   'debbugs-gnu-display-status'
 359             Show all bug attributes.
 360
 361 'C-c # t'   'debbugs-gnu-toggle-tag'
 362             Toggle local tag of bugs.
 363
 364 'C-c # C'   'debbugs-gnu-send-control-message'
 365             Send a control message for this bug, *note Control Messages::.
 366
 367
 368    When the bug attributes are shown by 'org-cycle', there is a link
 369 'Messages' which opens a GNUS ephemeral group for that bug.
 370
 371 \1f
 372 File: debbugs-ug.info,  Node: Control Messages,  Prev: TODO Items,  Up: Layout
 373
 374 3.3 Control Messages
 375 ====================
 376
 377 Debbugs control messages are sent by email to the GNU Debbugs control
 378 server.  Their format is described in
 379 <http://debbugs.gnu.org/server-control.html>.
 380
 381    A control message can be initiated in the tabulated list of bugs, in
 382 the list of org TODO items, or in the GNUS ephemeral group opened for
 383 the messages belonging to a given bug.  In the minibuffer, the following
 384 control messages can be requested (assuming that 12345 is the bug the
 385 control message is intended for).  The strings show the exact format of
 386 the control messages.
 387
 388 'block'
 389 'unblock'
 390      "block|unblock 12345 by 54321"
 391
 392      The second bug number is read interactively.  It could be also a
 393      list of comma-separated bug numbers.
 394
 395 'close'
 396      "close 12345 25.1"
 397
 398      The second argument, the Emacs version, is read interactively.
 399
 400 'confirmed'
 401 'fixed'
 402 'help'
 403 'moreinfo'
 404 'notabug'
 405 'patch'
 406 'pending'
 407 'security'
 408 'unreproducible'
 409 'wontfix'
 410      "tags 12345 confirmed|fixed|help|moreinfo|notabug"
 411
 412      "tags 12345 patch|pending|security|unreproducible|wontfix"
 413
 414 'done'
 415 'donenotabug'
 416 'doneunreproducible'
 417 'donewontfix'
 418      "tags 12345 fixed|notabug|unreproducible|wontfix"
 419      "close 12345 25.1"
 420
 421      The second argument in the close message, the Emacs version, is
 422      read interactively.
 423
 424 'forcemerge'
 425 'merge'
 426      "forcemerge|merge 12345 54321"
 427
 428      The second bug number is read interactively.
 429
 430 'important'
 431 'minor'
 432 'normal'
 433 'serious'
 434 'wishlist'
 435      "severity 12345 important|minor|normal|serious|wishlist"
 436
 437 'invalid'
 438      "tags 12345 notabug"
 439      "tags 12345 wontfix"
 440      "close 12345"
 441
 442 'noowner'
 443      "noowner 12345"
 444
 445 'owner'
 446      "owner 12345 !"
 447
 448 'reassign'
 449      "reassign 12345 PACKAGE"
 450
 451      The package name on the GNU Debbugs server is read interactively.
 452
 453 'reopen'
 454      "reopen 12345"
 455
 456 'unarchive'
 457      "unarchive 12345"
 458
 459 'unmerge'
 460      "unmerge 12345"
 461
 462 'usertag'
 463      "user USERNAME"
 464      "usertag 12345 TAG"
 465
 466      The username, read interactively, is either a package name or an
 467      email address.  The tag to be set is also read interactively.
 468
 469 \1f
 470 File: debbugs-ug.info,  Node: Minor Mode,  Next: Command Index,  Prev: Layout,  Up: Top
 471
 472 4 Minor Mode
 473 ************
 474
 475 Emacs uses 'bug-reference.el' for adding hyperlinks to bugs in files
 476 like 'ChangeLog', or in commentary sections of other files.  The
 477 reference to such bugs have a specialized format, <Bug#12345>.  The
 478 hyperlinks are implemented as minor modes 'bug-reference-mode' and
 479 'bug-reference-prog-mode'.
 480
 481    This package adds a new minor mode 'debbugs-browse-mode' on top of
 482 them.  Instead of using the default built-in Emacs browser for a given
 483 bug reference, it opens a corresponding bug report buffer.  The customer
 484 option 'debbugs-browse-function' controls, whether 'debbugs-gnu-bugs' or
 485 'debbugs-org-bugs' is called.
 486
 487    This minor mode is applicable for all URLs, not only bug references.
 488 Any URL with the format <http://debbugs.gnu.org/12345> will be shown in
 489 a bug report buffer, when 'debbugs-browse-mode' is enabled.
 490
 491 \1f
 492 File: debbugs-ug.info,  Node: Command Index,  Next: Variable Index,  Prev: Minor Mode,  Up: Top
 493
 494 Command Index
 495 *************
 496
 497