admin/notes/bugtracker

   1 NOTES ON THE EMACS BUG TRACKER   -*- outline -*-
   2
   3 The Emacs Bug Tracker can be found at http://emacsbugs.donarmstrong.com/
   4
   5 For a list of all bugs, see http://emacsbugs.donarmstrong.com/emacs
   6
   7 ** How do I report a bug in Emacs now?
   8 The same way as you always did.  Send mail to bug-gnu-emacs@gnu.org,
   9 or use M-x report-emacs-bug.
  10
  11 The only differences are:
  12
  13 i) Your report will be assigned a number and generate an automatic reply.
  14
  15 ii) Optionally, you can set some database parameters when you first
  16 report a bug (see "Setting bug parameters" below).
  17
  18 iii) If you want to CC: someone, use X-Debbugs-CC: (this is important;
  19 see below).
  20
  21 Once your report is filed and assigned a number, it is sent out to the
  22 bug mailing list.  In some cases, it may be appropriate to just file a
  23 bug, without sending out a copy.  To do this, send mail to
  24 quiet@emacsbugs.donarmstrong.com.
  25
  26 ** How do I reply to an existing bug report?
  27 Reply to 123@emacsbugs.donarmstrong.com, replacing 123 with the number
  28 of the bug you are interested in.  NB this only sends mail to the
  29 bug-list, it does NOT (?) send a CC to the original bug submitter.
  30 So you need to explicitly CC him/her (and anyone else you like).
  31
  32 (Many people think the submitter SHOULD be automatically subscribed
  33 to subsequent discussion, but this does not seem to be implemented.
  34 See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=37078)
  35
  36 Do NOT send a separate copy to the bug list, since this may generate a
  37 new report. The only time to send mail to the bug list is to create a
  38 new report.
  39
  40 Gnus users can add the following to message-dont-reply-to-names;
  41 similarly with Rmail and rmail-dont-reply-to-names:
  42
  43 "\\(emacs-pretest-bug\\|bug-gnu-emacs\\)@gnu\\.org\\|\
  44 \\(\\(submit\\|control\\|owner\\)@emacsbugs\\.\\|bug-submit-list@\\)\
  45 donarmstrong\\.com"
  46
  47 The "bug-submit-list@donarmstrong.com" and
  48 "owner@emacsbugs.donarmstrong.com" entries are there because they can
  49 appear in the "Resent-To" and "Resent-CC" headers, respectively. For a
  50 long time Rmail erroneously included these headers in replies.  If you
  51 correspond with an Rmail user on a bug, these addresses may end up in
  52 the Cc.  Mailing to them does nothing but create duplicates and errors.
  53 (It is possible you might want to have a dialog with the owner
  54 address, outside of normal bug reporting.)
  55
  56 ** When reporting a bug, to send a Cc to another address
  57 (e.g. bug-cc-mode@gnu.org), do NOT just use a Cc: header.
  58 Instead, use "X-Debbugs-CC:".  This ensures the Cc address will get a
  59 mail with the bug report number in.  If you do not do this, each reply
  60 in the subsequent discussion will end up creating a new bug.  This is
  61 annoying.
  62
  63 Note that the way this feature works is perhaps not ideal (Bug#1720).
  64 If X-Debbugs-CC: was specifed by a real header, that header is removed
  65 in the mail sent out to the bug list, and the addresses merged into
  66 the Resent-CC header (see below).  They don't appear as an explicit CC:
  67 header, nor do they appear in the Reply-To: header.  So people you
  68 X-Debbugs-CC are not included in any following discussion unless they are
  69 manually cc'd.  So this feature really only serves to notify them that
  70 a bug has been filed.  It's then up to them to follow any subsequent
  71 discussion.
  72
  73 If X-Debbugs-CC were merged into the Reply-To header, this might work
  74 more the way people expect.
  75
  76 ** How does Debbugs send out mails?
  77
  78 The mails are sent out to the bug list with From: and To: unchanged.
  79 Eg if you file a bug with "submit@emacsbugs.donarmstrong.com", that
  80 remains in the To: address.  They reach the bug list by being resent.
  81
  82 Mails arriving at the bug list have the following Resent-* headers:
  83
  84 Resent-From: person who submitted the bug
  85 Resent-To:   bug-submit-list@donarmstrong.com
  86 Resent-CC:   maintainer email address, plus any X-Debbugs-CC: entries
  87
  88 The "maintainer email address" is "Emacs Bugs <bug-gnu-emacs@gnu.org>"
  89 in most cases.
  90
  91 They also have:
  92
  93 Reply-To:   bug submitter, 123@emacsbugs.donarmstrong.com
  94
  95 ** To not get acknowledgement mail from the tracker,
  96 add an "X-Debbugs-No-Ack:" header (with any value).  If you use Gnus,
  97 you can add an element to gnus-posting-styles to do this automatically, eg:
  98
  99 ("gnu-emacs\\(-pretest\\)?-bug"
 100    ("X-Debbugs-No-Ack" "yes"))
 101
 102 (adjust the regexp according to the name you use for the bug lists)
 103
 104 ** To record a bug in the tracker without sending mail to the bug list.
 105 This can be useful to make a note of something discussed on
 106 emacs-devel that needs fixing.  In other words, this can be the
 107 equivalent of adding something to FOR-RELEASE.
 108
 109 To: quiet@emacsbugs.donarmstrong.com
 110 [headers end]
 111 Package: emacs
 112 Version: 23.0.60
 113 Severity: minor
 114
 115 Remember to fix FOO, as discussed on emacs-devel at http://... .
 116
 117 ** Not interested in tracker control messages (tags being set, etc)?
 118 Discard mails matching:
 119
 120 ^X-Emacs-PR-Message: transcript
 121
 122 When you close a bug, you get a message matching:
 123
 124 ^X-Emacs-PR-Message: closed
 125
 126 ** How to avoid multiple copies of mails.
 127 When you reply to a bug, respect the Reply-To address, ie send mail
 128 only to the submitter address and the numbered bug address.  Do not
 129 send mail direct to bug-gnu-emacs or emacs-pretest-bug unless you are
 130 reporting a new bug.
 131
 132 ** To close bug #123 (for example), send mail
 133
 134 To: 123-done@emacsbugs.donarmstrong.com
 135
 136 with a brief explanation in the body as to why the bug was closed.
 137
 138 ** Setting bug parameters.
 139 There are two ways to set the parameters of bugs in the database
 140 (tags, severity level, etc).  When you report a new bug, you can
 141 provide a "pseudo-header" at the start of the report, eg:
 142
 143 Package: emacs
 144 Version: 23.0.60
 145 Severity: minor
 146
 147 Optionally, add a sub-package, eg Package: emacs,calendar.
 148 This can include tags.  Some things (e.g. submitter) don't seem to
 149 work here.
 150
 151 Otherwise, send mail to the control server, control@emacsbugs.donarmstrong.com.
 152 At the start of the message body, supply the desired commands, one per
 153 line:
 154
 155 command bug-number [arguments]
 156 ...
 157 quit|stop|thank|thanks|thankyou|thank you
 158
 159 The control server ignores anything after the last line above.  So you
 160 can place control commands at the beginning of a reply to a bug
 161 report, and Bcc: the control server (note the commands have no effect
 162 if you just send them to the bug-report number).  Bcc: is better than Cc:
 163 in case people use Reply-to-All in response.
 164
 165 Some useful control commands:
 166
 167 *** To reopen a closed bug:
 168 reopen 123
 169
 170 *** Bugs can be tagged in various ways (eg wontfix, patch, etc).
 171 The available tags are:
 172 patch wontfix moreinfo unreproducible fixed notabug
 173 Note that the list at http://emacsbugs.donarmstrong.com/Developer#tags
 174 is incorrect, at least for Emacs.
 175 The list of tags can be prefixed with +, - or =, meaning to add (the
 176 default), remove, or reset the tags. E.g.:
 177
 178 tags 123 + wontfix
 179
 180 *** To merge bugs:
 181 Eg when bad replies create a bunch of new bugs for the same report.
 182 Bugs must all be in the same state (e.g. same package(s) and severity
 183 -- see `reassign' and `severity' below), but need not have the same
 184 tags (tags are merged). E.g.:
 185
 186 merge 123 124 125 ...
 187
 188 Note that merging does not affect titles.  In particular, a "retitle"
 189 of merged bugs only affects individual bugs, not all of them.
 190
 191 *** Forcing a merge:
 192 Like `merge', but bugs need not be in the same state.  The packages
 193 must still match though (see `reassign' below).  The first one listed
 194 is the master.  E.g.:
 195
 196 forcemerge 123 124 125 ...
 197
 198 Note: you cannot merge with an archived bug - you must unarchive it first.
 199
 200 *** To unmerge bugs:
 201 To disconnect a bug from all bugs it is merged with:
 202
 203 unmerge 123
 204
 205 This command accepts only one bug number.
 206
 207 *** To clone bugs:
 208 Useful when one report refers to more than one bug.
 209
 210 clone 123 -1 [-2 ...]
 211 retitle -1 second bug
 212 retitle -2 third bug
 213
 214 The negative numbers provide a way to refer to the cloned bugs (which
 215 will be assigned proper numbers).
 216
 217 NB you cannot clone a merged bug.  You'd think that trying to do so
 218 would just give you an unmerged copy of the specified bug number, but no:
 219
 220 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=474742
 221
 222 You must unmerge, clone, then re-merge.
 223
 224 *** To set severity:
 225 severity 123 critical|grave|serious|important|normal|minor|wishlist
 226
 227 See http://emacsbugs.donarmstrong.com/Developer#severities for the meanings.
 228
 229 *** To set the owner of a bug:
 230 owner 123 A Hacker <none@example.com>
 231
 232 The shorthand `!' means your own address.
 233
 234 *** To remove the owner of a bug:
 235 noowner 123
 236
 237 *** To mark a bug as fixed in a particular version:
 238 fixed 123 23.0.60
 239
 240 *** To remove a "fixed" mark:
 241 notfixed 123 23.0.60
 242
 243 *** To assign or reassign a bug to a package or list of packages:
 244 reassign 1234 emacs,cc-mode
 245
 246 ** To remove spam from the tracker, move it to the `spam' pseudo-package:
 247 reassign 123 spam
 248
 249 ** To change the title of a bug:
 250 retitle 123 Some New Title
 251
 252 ** To change the submitter address:
 253 submitter 123 none@example.com
 254
 255 Note that it does not seem to work to specify "Submitter:" in the
 256 pseudo-header when first reporting a bug.
 257
 258 ** How does archiving work?
 259 You can still send mail to a bug after it is closed.  After 28 days with
 260 no activity, the bug is archived, at which point no more changes can
 261 be made.  If you try to send mail to the bug after that (or merge with
 262 it), it will be rejected.  To make any changes, you must unarchive it first:
 263
 264 unarchive 123
 265
 266 The bug will be re-archived after the next 28 day period of no activity.
 267
 268 ** The web-page with the list of bugs is slow to load
 269
 270 It's a function of the number of displayed bugs.  You can speed things
 271 up by only looking at the newest 100 bugs:
 272
 273 http://emacsbugs.donarmstrong.com/cgi-bin/pkgreport.cgi?newest=100;package=emacs
 274
 275 The above page is accessible from the "Options" section at the end of
 276 the "main list of bugs" page. Select bugs "in package" = emacs;
 277 "newest bugs" = 100.  (I have no idea how you get to that Options
 278 section without having to go through the bug list page first...)
 279
 280 ** Mails to the bug tracker disappear
 281
 282 Apparently it has some kind of spam filter that sometimes silently
 283 discards valid mails. Adding a subject (pointless in control messages)
 284 may help.
 285
 286 ** ChangeLog issues
 287
 288 *** When you fix a bug, it can be helpful to put the bug number in the
 289 ChangeLog entry, for example:
 290
 291    * foo.el (foofunc): Fix the `foo' case.  (Bug#123)
 292
 293 Then the relevant bug can be found for easy reference.  If it's an
 294 obvious fix (e.g. a typo), there's no need to clutter the log with the
 295 bug number.
 296
 297 Similarly, when you close a bug, it can be helpful to include the
 298 relevant ChangeLog entry in the message to the bug tracker, so people
 299 can see eaxctly what the fix was.
 300
 301 *** bug-reference-mode
 302
 303 Activate `bug-reference-mode' in ChangeLogs to get clickable links to
 304 the bug web-pages.
 305
 306 ** Gnus-specific voodoo
 307
 308 *** Put point on a bug-number and try: M-x gnus-read-ephemeral-emacs-bug-group
 309
 310 *** If the above is not available:
 311 (add-hook 'gnus-article-mode-hook
 312           (lambda ()
 313              (setq bug-reference-url-format
 314                "http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=%s")
 315               (bug-reference-mode 1)))
 316
 317 and you can click on the bug number in the subject header.