Xen Bug Management Interface

Introduction

This page gives information on how to use the Xen bug tracker.

Reporting a Bug

Bugs should continue to be reported to the Xen Devel mailing list following the guidelines given in Reporting Bugs against Xen.

There is no need to interact with the bug tracking system in order to report a bug.

Bug Control Messages

Overview

Bugs in the Xen bug tracking system are manipulated by sending mail to the bug control bot at: xen (at) bugs.xenproject.org. Often this will be done by Bcc'ing the bot on the xen-devel thread containing the bug. Using Bcc helps ensure that subsequent mails in the thread which are not intended for the bot's consumption are not needlessly sent there.

The control bot will reply with the results of your messages. If everything was successful a copy of the response will also be sent to the list.

The commands understood are documented at http://bugs.xenproject.org/xen/static/control.txt.

The bot will process the message a line at a time until it either encounters an error or reaches one of the termination commands ("thanks", "quit", "goodbye", "stop"). Since it is expect that normally the control bot will simply be bcc'd on a message in the thread and this therefore allows the usual message content to follow.

Although it would be normal for control messages to also go to the list it is not strictly required. However mails which are referenced by a bug must be sent to the list or they cannot be included in the bug log.

Common Operations

Creating a Bug

Once a bug has been reported to the list a developer can choose to register it with the Bug tracker. This is done by sending a mail to the bug system control bot using the create command:

 create <reference to an email>
 thanks
 <remainder of the email goes here, ignored by the bot>

Where "<reference to an email>" is either:

• The message-id of the message to treat as the root of the bug. This can be the message which started the thread or the message at the base of an arbitrary subthread.
• A literal "!" (without quotes) -- this is a shorthand for this message (i.e. the one the bot is currently processing).
• A literal "^" (without quotes) -- this is a shorthand for the message which this mail is a reply to. Useful if you are replying to the original bug message.

Usually this would be done by replying to the mail thread on the list and sending copy (usually via bcc) to the control bot.

For example if a user reports a bug:

 From: A User <a.user@example.com>
 To: xen-devel@lists.xen.org
 Subject: [BUG] frobnitz does not work properly
 Message-Id: <message-12345@example.com>
 
 Hi, We I try to frobnitz my woggle it segfaults.
 ... details, config etc ...

Then a developer might reply with:

 From: A Developer <adev@xen.org>
 To: A User <a.user@example.com>
 Cc: xen-devel@lists.xen.org
 Bcc: xen@bugs.xenproject.org
 Message-Id: [...]
 References: <message-12345@example.com>
 
 create ^
 thanks
 
 "A User" wrote:
 > Hi, When I try to frobnitz my woggle it segfaults.
 > ...
 
 Thanks, this does indeed seem to be a bug. I'm afraid I don't have
 time to look into it right now but I have created an entry in our
 bug tracker so that it doesn't get forgotten.

This would create a bug starting from the mail <message-12345@example.com> which is implied by the ^ which means "the message replied to here".

If instead the report was incomplete and required some back and forth a developer might reply to a message further down the thread:

 From: A Developer <adev@xen.org>
 To: A User <a.user@example.com>
 Cc: xen-devel@lists.xen.org
 Bcc: xen@bugs.xenproject.org
 Message-Id: [...]
 References: <message-7890@example.com> [...] <message-12345@example.com>
 
 create <message-12345@example.com>
 thanks
 
 "A User" wrote:
 > "A Developer" wrote:
 > > "A User" wrote:
 > > > Hi, When I try to frobnitz my woggle it doesn't work.
 > > Why not, what happens exactly?
 > When I try it segfaults, here is a back trace.
 
 Great thanks, this does indeed seem to be a bug. I'm afraid I don't
 have time to look into it right now but I have created an entry in
 our bug tracker so that it doesn't get forgotten.

This would create a bug by explicitly referencing the message with id <message-12345@example.com>. If A Developer had instead used ^ then a bug would be created referencing the Users message containing "When I try it segfaults, ...". Depending on the content the preceding thread this may or may not be a useful place to start recording.

There is a third option which is to use the ! specifier which creates a bug from the current mail. When using this option it is important to remember to copy the list and to quote all of the relevant parts of the users mail since only

Closing a bug

To close a bug send a message to the control bot with the command close N where N is the bug number. It would normally be useful to send this message to the list and the reporter also explaining why the bug is being closed. e.g.

 From: A Developer <adev@xen.org>
 To: A User <a.user@example.com>
 Cc: xen-devel@lists.xen.org
 Bcc: xen@bugs.xenproject.org
 Message-Id: [...]
 
 close 6
 thanks
 
 Hi A, I think this bug is now fixed with commit XXXYYY.
 
 Thanks again for your bug report.
 
 Developer.

Retitling, changing severity, owner etc

See http://bugs.xenproject.org/xen/static/control.txt for the full list of commands understood by the control bot.

You can send mail to the control bot containing these commands at any time. In addition you can use them in the same mail as you create a message by specifying "it" as the bug number. it in this context refers to the most recently referenced bug, i.e. usually the one you have just created. e.g.

 From: A Developer <adev@xen.org>
 To: A User <a.user@example.com>
 Cc: xen-devel@lists.xen.org
 Bcc: xen@bugs.xenproject.org
 Message-Id: [...]
 References: <message-12345@example.com>
 
 create ^
 title it Frobnitzer segfaults on use
 severity it blocker
 thanks
 
 "A User" wrote:
 > Hi, When I try to frobnitz my woggle it segfaults.
 > ...
 
 Thanks, this does indeed seem to be a bug. I'm afraid I don't have
 time to look into it right now but I have created an entry in our
 bug tracker so that it doesn't get forgotten. The frobnitzer is a
 rather key component so we can't release with it in this state,
 hence setting severity to blocker.

Best Practices

Note: Since the use of this system is still in its infancy these are really just early suggestions on how things might work.

Why BCC and not CC the control address

This avoids subsequent replies in the thread from needlessly going to the control bot. Its harmless but you might find the innevitable replies from the bot reporting "syntax error" irritating.

When to register a bug for tracking

This is up to you as a developer. Any time a user reports a bug which you cannot deal with at the moment or which you feel requires tracking for some reason seem like a good time. However in order to avoid filling the tracker with untriaged or incomplete bugs please consider working with the reporter to gather enough information (descriptions, logs etc) before marking the bug to be tracked.

Multiple bug reports in the same email

Although users are encouraged to submit bug in separate mails inevitably we will end up with multiple bugs in a single mail. The best way to deal with this is probably to reply to the report multiple times quoting only the material relating to a single bug and using the create ! syntax to track the new subthread.

When to copy a control message to the list as well

In general you should copy the list whenever the mail contains useful context or other information apart from the control commands. In the common case you will likely be replying to the list anyway.