view admin/notes/bugtracker @ 106412:3fea95b17dfa

(vc-dir): Use the correct markup for showing keymaps in docstrings.

NOTES ON THE EMACS BUG TRACKER   -*- outline -*-

The Emacs Bug Tracker can be found at http://emacsbugs.donarmstrong.com/

For a list of all bugs, see http://emacsbugs.donarmstrong.com/emacs

** How do I report a bug in Emacs now?
The same way as you always did.  Send mail to [e-mail],
or use M-x report-emacs-bug.

The only differences are:

i) Your report will be assigned a number and generate an automatic reply.

ii) Optionally, you can set some database parameters when you first
report a bug (see "Setting bug parameters" below).

iii) If you want to CC: someone, use X-Debbugs-CC: (this is important;
see below).

Once your report is filed and assigned a number, it is sent out to the
bug mailing list.  In some cases, it may be appropriate to just file a
bug, without sending out a copy.  To do this, send mail to
[e-mail].

** How do I reply to an existing bug report?
Reply to [e-mail], replacing 123 with the number
of the bug you are interested in.  NB this only sends mail to the
bug-list, it does NOT (?) send a CC to the original bug submitter.
So you need to explicitly CC him/her (and anyone else you like).

(Many people think the submitter SHOULD be automatically subscribed
to subsequent discussion, but this does not seem to be implemented.
See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=37078)

Do NOT send a separate copy to the bug list, since this may generate a
new report. The only time to send mail to the bug list is to create a
new report.

Gnus users can add the following to message-dont-reply-to-names;
similarly with Rmail and rmail-dont-reply-to-names:

"\\(emacs-pretest-bug\\|bug-gnu-emacs\\)@gnu\\.org\\|\
\\(\\(submit\\|control\\|owner\\)@emacsbugs\\.\\|bug-submit-list@\\)\
donarmstrong\\.com"

The "[e-mail]" and
"[e-mail]" entries are there because they can
appear in the "Resent-To" and "Resent-CC" headers, respectively. For a
long time Rmail erroneously included these headers in replies.  If you
correspond with an Rmail user on a bug, these addresses may end up in
the Cc.  Mailing to them does nothing but create duplicates and errors.
(It is possible you might want to have a dialog with the owner
address, outside of normal bug reporting.)

** When reporting a bug, to send a Cc to another address
(e.g. [e-mail]), do NOT just use a Cc: header.
Instead, use "X-Debbugs-CC:".  This ensures the Cc address will get a
mail with the bug report number in.  If you do not do this, each reply
in the subsequent discussion will end up creating a new bug.  This is
annoying.

Note that the way this feature works is perhaps not ideal (Bug#1720).
If X-Debbugs-CC: was specifed by a real header, that header is removed
in the mail sent out to the bug list, and the addresses merged into
the Resent-CC header (see below).  They don't appear as an explicit CC:
header, nor do they appear in the Reply-To: header.  So people you
X-Debbugs-CC are not included in any following discussion unless they are
manually cc'd.  So this feature really only serves to notify them that
a bug has been filed.  It's then up to them to follow any subsequent
discussion.

If X-Debbugs-CC were merged into the Reply-To header, this might work
more the way people expect.

** How does Debbugs send out mails?

The mails are sent out to the bug list with From: and To: unchanged.
Eg if you file a bug with "[e-mail]", that
remains in the To: address.  They reach the bug list by being resent.

Mails arriving at the bug list have the following Resent-* headers:

Resent-From: person who submitted the bug
Resent-To:   [e-mail]
Resent-CC:   maintainer email address, plus any X-Debbugs-CC: entries

The "maintainer email address" is "Emacs Bugs <[e-mail]>"
in most cases.

They also have:

Reply-To:   bug submitter, [e-mail]

** To not get acknowledgement mail from the tracker,
add an "X-Debbugs-No-Ack:" header (with any value).  If you use Gnus,
you can add an element to gnus-posting-styles to do this automatically, eg:

("gnu-emacs\\(-pretest\\)?-bug"
   ("X-Debbugs-No-Ack" "yes"))

(adjust the regexp according to the name you use for the bug lists)

** To record a bug in the tracker without sending mail to the bug list.
This can be useful to make a note of something discussed on
emacs-devel that needs fixing.  In other words, this can be the
equivalent of adding something to FOR-RELEASE.

To: [e-mail]
[headers end]
Package: emacs
Version: 23.0.60
Severity: minor

Remember to fix FOO, as discussed on emacs-devel at http://... .

** Not interested in tracker control messages (tags being set, etc)?
Discard mails matching:

^X-Emacs-PR-Message: transcript

When you close a bug, you get a message matching:

^X-Emacs-PR-Message: closed

** How to avoid multiple copies of mails.
When you reply to a bug, respect the Reply-To address, ie send mail
only to the submitter address and the numbered bug address.  Do not
send mail direct to bug-gnu-emacs or emacs-pretest-bug unless you are
reporting a new bug.

** To close bug #123 (for example), send mail

To: [e-mail]

with a brief explanation in the body as to why the bug was closed.
There is no need to cc the address without the "-done" part or the
submitter; they get copies anyway so this will just result in more
duplicate mail.

** Setting bug parameters.
There are two ways to set the parameters of bugs in the database
(tags, severity level, etc).  When you report a new bug, you can
provide a "pseudo-header" at the start of the report, eg:

Package: emacs
Version: 23.0.60
Severity: minor

Optionally, add a sub-package, eg Package: emacs,calendar.
This can include tags.  Some things (e.g. submitter) don't seem to
work here.

Otherwise, send mail to the control server, [e-mail].
At the start of the message body, supply the desired commands, one per
line:

command bug-number [arguments]
...
quit|stop|thank|thanks|thankyou|thank you

The control server ignores anything after the last line above.  So you
can place control commands at the beginning of a reply to a bug
report, and Bcc: the control server (note the commands have no effect
if you just send them to the bug-report number).  Bcc: is better than Cc:
in case people use Reply-to-All in response.

Some useful control commands:

*** To reopen a closed bug:
reopen 123

*** Bugs can be tagged in various ways (eg wontfix, patch, etc).
The available tags are:
patch wontfix moreinfo unreproducible fixed notabug
Note that the list at http://emacsbugs.donarmstrong.com/Developer#tags
is incorrect, at least for Emacs.
The list of tags can be prefixed with +, - or =, meaning to add (the
default), remove, or reset the tags. E.g.:

tags 123 + wontfix

** Usertags

See <http://wiki.debian.org/bugs.debian.org/usertags>

"Usertags" are very similar to tags: a set of labels that can be added
to a bug.  There are two differences between normal tags and user
tags:

1) Anyone can define any valid usertag they like.  In contrast, only a
limited, predefined set of normal tags are available (see above).

2) A usertag is associated with a specific email address.

You set usertags in the same way as tags, by talking to the control
server.  One difference is that you can also specify the associated
email address.  If you don't explicitly specify an address, then it
will use the one from which you send the control message. The address
must have the form of an email address (with an "@" sign and least 4
characters after the "@").

*** Setting usertags

a) In a control message:

user [e-mail]
usertags 1234 any-tag-you-like

This will add a usertag "any-tag-you-like" to bug 1234.  The tag will
be associated with the address "[e-mail]".  If you omit
the first line, the tag will be associated with your email address.

The syntax of the usertags command is the same as that of tags (eg wrt
the optional [=+-] argument).

b) In an initial submission, in the pseudo-header:

User: [e-mail]
Usertags: a-new-tag

Again, the "User" is optional.

*** Searching by usertags

The search interface is not as advanced as for normal tags.  You need
to construct the relevant url yourself rather than just typing in a
search box.  The only piece you really need to add is the "users"
portion, the rest has the same syntax as normal.

**** To find all bugs usertagged by a given email address:

http://debbugs.gnu.org/cgi/pkgreport.cgi?users=[e-mail]

(Supposedly, the "users" field can be a comma-separated list of more
than one email address, but it does not seem to work for me.)

**** To find bugs tagged with a specific usertag:

This works just like a normal tags search, but with the addition of a
"users" field.  Eg:

http://debbugs.gnu.org/cgi/pkgreport.cgi?users=[e-mail];tag=calendar

*** To merge bugs:
Eg when bad replies create a bunch of new bugs for the same report.
Bugs must all be in the same state (e.g. same package(s) and severity
-- see `reassign' and `severity' below), but need not have the same
tags (tags are merged). E.g.:

merge 123 124 125 ...

Note that merging does not affect titles.  In particular, a "retitle"
of merged bugs only affects individual bugs, not all of them.

*** Forcing a merge:
Like `merge', but bugs need not be in the same state.  The packages
must still match though (see `reassign' below).  The first one listed
is the master.  E.g.:

forcemerge 123 124 125 ...

Note: you cannot merge with an archived bug - you must unarchive it first.

*** To unmerge bugs:
To disconnect a bug from all bugs it is merged with:

unmerge 123

This command accepts only one bug number.

*** To clone bugs:
Useful when one report refers to more than one bug.

clone 123 -1 [-2 ...]
retitle -1 second bug
retitle -2 third bug

The negative numbers provide a way to refer to the cloned bugs (which
will be assigned proper numbers).

NB you cannot clone a merged bug.  You'd think that trying to do so
would just give you an unmerged copy of the specified bug number, but no:

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=474742

You must unmerge, clone, then re-merge.

*** To set severity:
severity 123 critical|grave|serious|important|normal|minor|wishlist

See http://emacsbugs.donarmstrong.com/Developer#severities for the meanings.

*** To set the owner of a bug:
owner 123 A Hacker <[e-mail]>

The shorthand `!' means your own address.

*** To remove the owner of a bug:
noowner 123

*** To mark a bug as fixed in a particular version:
fixed 123 23.0.60

*** To remove a "fixed" mark:
notfixed 123 23.0.60

*** To assign or reassign a bug to a package or list of packages:
reassign 1234 emacs,cc-mode

** To remove spam from the tracker, move it to the `spam' pseudo-package:
reassign 123 spam

** To change the title of a bug:
retitle 123 Some New Title

** To change the submitter address:
submitter 123 [e-mail]

Note that it does not seem to work to specify "Submitter:" in the
pseudo-header when first reporting a bug.

** How does archiving work?
You can still send mail to a bug after it is closed.  After 28 days with
no activity, the bug is archived, at which point no more changes can
be made.  If you try to send mail to the bug after that (or merge with
it), it will be rejected.  To make any changes, you must unarchive it first:

unarchive 123

The bug will be re-archived after the next 28 day period of no activity.

** The web-page with the list of bugs is slow to load

It's a function of the number of displayed bugs.  You can speed things
up by only looking at the newest 100 bugs:

http://emacsbugs.donarmstrong.com/cgi-bin/pkgreport.cgi?newest=100;package=emacs

The above page is accessible from the "Options" section at the end of
the "main list of bugs" page. Select bugs "in package" = emacs;
"newest bugs" = 100.  (I have no idea how you get to that Options
section without having to go through the bug list page first...)

** Mails to the bug tracker disappear

Apparently it has some kind of spam filter that sometimes silently
discards valid mails. Adding a subject (pointless in control messages)
may help.

** ChangeLog issues

*** When you fix a bug, it can be helpful to put the bug number in the
ChangeLog entry, for example:

   * foo.el (foofunc): Fix the `foo' case.  (Bug#123)

Then the relevant bug can be found for easy reference.  If it's an
obvious fix (e.g. a typo), there's no need to clutter the log with the
bug number.

Similarly, when you close a bug, it can be helpful to include the
relevant ChangeLog entry in the message to the bug tracker, so people
can see eaxctly what the fix was.

*** bug-reference-mode

Activate `bug-reference-mode' in ChangeLogs to get clickable links to
the bug web-pages.

*** Debian stuff

http://lists.gnu.org/archive/html/emacs-devel/2009-11/msg00440.html

** Gnus-specific voodoo

*** Put point on a bug-number and try: M-x gnus-read-ephemeral-emacs-bug-group

*** If the above is not available:
(add-hook 'gnus-article-mode-hook
          (lambda ()
             (setq bug-reference-url-format
               "http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=%s")
              (bug-reference-mode 1)))

and you can click on the bug number in the subject header.