Using this system to track your project's bugs

This tracker is available for use by official GNU software, and by Savannah-hosted non-GNU free software. If you are the maintainer of such a package and would like to use it, send a mail to the help-debbugs mailing list.

If you want to use the system, you need to supply the following information:

  1. The name of your package. Your bugs will be visible at http://debbugs.gnu.org/package .
  2. A maintainer email address. This can be a bug mailing list (recommended) or your personal email address. (Note that any mailing list must already exist - we cannot create it for you.)
  3. Links to your project's homepage, the archive for your bug mailing lists, and to your instructions for bug reporting; for use in the packages table.
If your maintainer email is a mailing list, turn off any subject prefix (it can lead to the bug number being repeatedly added to the subject in each subsequent reply).

If you are using a lists.gnu.org bug mailing list (or if you have control over the routing for your mail domain), the system can optionally "take over" your bug list, such that messages sent to the list that are not replies to existing topics automatically create new bug reports. This is the recommended mode of operation (so-called "exclusive" mode; see technical details below).

In this case, your bug mailing list address effectively becomes an alias for submit AT debbugs.gnu.org. You will need to provide a list of all the aliases (if any) by which your bug mailing list is known (for example: bug-gnu-emacs, emacs-pretest-bug, bug-emacs, bug-gnumacs). This is because we use the recipient address to identify the package if one is not explicitly specified in a pseudo-header. You may find there are more aliases than you think - check /etc/aliases on fencepost!

Technical Details of How it Works

We define a package for your project (eg emacs) and an associated maintainer email address. Normally this would be your bug mailing list address (eg bug-gnu-emacs AT gnu.org), but if you want to test it out first you could use your personal email address. Then there are two ways you can use it:

  1. Exclusive mode. This is the recommended mode, and is how eg Emacs, Coreutils use it. Debbugs essentially takes complete control over your bug mailing list. Every mail sent to your bug list that is not in response to an existing bug creates a new bug report. Replies to existing bug reports (identified by subject, eg "Re: bug#123"; recipient address, eg "To: 123@debbugs"; or as a last resort message-id) are appended to those reports. (If you are using another tracker, eg Savannah's, to send mail to that list, you will want to turn it off, or send it elsewhere, otherwise they will interfere with each other. Specifically, every comment sent to the Savannah tracker will open a new report in debbugs.)

    The advantage of this mode is that your bug submitters do not need to do anything special. They just report bugs to your bug mailing list in the normal way, and numbered bug reports are automatically created.

    You will want to warn people before turning this on, since replies to older discussions will create new bug numbers the first time they are processed by the system.

    This mode is achieved by turning on a router rule (a simple alias is not enough) for your mailing list address, so that any mails that do not come from debbugs.gnu.org are first redirected to that machine. This is implemented automatically: there is a config file on debbugs.gnu.org that defines the lists to be routed in this way, and it is periodically checked for new lists.

  2. Non-exclusive mode. This is how eg the debbugs.gnu.org package itself operates. To report bugs, people must send mail to a special address ("submit@debbugs"), using a "pseudo-header" (eg "Package: emacs") to indicate which of the packages using debbugs.gnu.org their bug is about. If they forget to include a package, it will be assigned to the default package (which is debbugs.gnu.org itself). The advantage of this mode is that it allows the maintainer address to be used for both bug reports and non-bug discussion. So you may want to use this mode if you do not have a dedicated bug mailing list (eg the help-debbugs list is used for both bugs and general discussion). The disadvantage is the need to use a special address (and syntax) to create a bug report.

Moderation of Input

All submissions are moderated using Mailman. If you want to use the tracker for your project, you might want to sign up as a moderator, perhaps just to keep an eye on your reports, but it is not compulsory. See moderation details.

If debbugs has exclusive control of your bug mailing list, you should find the bug mailing list itself no longer needs any explicit moderation, and you might want to turn that off. The one exception may be if your bug mailing list is gatewayed to a newsgroup. This doesn't seem to work right - mails originally sent to the newsgroup seem to end up straight on the bug mailing list without going through the tracker. There seems to be no prospect of fixing that. You can add a Mailman spam filter that traps anything with a "Newsgroups" header.

Testing

Supply a package name and maintainer address (eg your personal address), then test the system out. Tests bugs can be completely deleted from the database once you are done.

Importing bugs

I'm not aware of any tools that do this. You could send a summary of each existing bug as a separate mail to quiet@debbugs, in order to get old bugs in the tracker. If your previous bugs take the form of emails, you could just resend each mail involved in a given report to debbugs (with a small amount of care).

Exporting bugs

A bug report is basically just an mbox file. On the web-page for every bug report are links to download mbox folders containing all the mails involved in every bug report.

Internally, debbugs stores everything as plain text files. The main file is a collection of mail messages, with small "format" sections inbetween each mail. There are a couple of small files that summarize the status. It would be easy to tar up all the files relating to a given package and provide them to the maintainer of that package, if say you wanted to move your bugs somewhere else.

Missing Features

There are some features that the system does not have: Basically, if you are using a standard bug-foo@gnu mailing list at the moment, the system will fairly transparently hook this into a bug database, so that new reports automatically generate new bugs, without otherwise much changing the way you do things. This appeals to some but not to others.

Procedure for adding a new project

Add an entry to /var/www/Packages.html, and to the following files in /etc/debbugs: Maintainers, Lists, and (if using exclusive mode) exim (for a nongnu.org mailing list, use exim.nongnu instead). Run the script /var/www/rrd/make_html.

Details:
The exim(.nongnu) file controls which mailing lists get redirected to debbugs (this aspect is controlled by FSF sysadmins). The Lists file is used to map incoming mails to packages, based on the To address (it should contain any email aliases for each mailing list). The Maintainers file says where mail about each package is sent out to.

If you have any questions, contact help-debbugs AT gnu.org.

Back to index.

Last modified: <Saturday 19 March 2022, 16:00:51 EDT>

Debbugs bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.