How to use the Bug Tracking System
This is a tutorial about how to use the Bug Tracking System (BTS).
The acronym BTS stands for Bug Tracking System and is where Debian stores and tracks reported bugs (including wishlist reports, not only "real" bugs). It is mainly an email system: tweaking and manipulating it can only be done via sending emails to the system. The mails must be sent in text format and not HTML.
Querying bug reports: the BTS web interface
The web interface of BTS can be found at http://bugs.debian.org/. Through this web interface you can query for reported bugs quite quickly (if the server isn't too loaded) and extremely conveniently, too.
If you go to http://bugs.debian.org/ you are redirected to a page that offers you a form through which you can search but the most useful thing about bugs.debian.org is the more specific redirects that it offers:
If you are maintaining packages yourself, you can go to http://email@example.com and see all the (outstanding) bug reports in all the packages you maintain with that given email address.
If on the other hand, you report bug reports, you can get a list of the bug reports from you that haven't yet been fixed by going to http://bugs.debian.org/from:firstname.lastname@example.org.
If you want to report a new bug, you should always check first to see whether the bug has already been reported. To do this, you can go to http://bugs.debian.org/packagename to get a list of all the bug reports for a given package. Note that 'packagename' here is the name of the binary package.
Maybe you want to see a combined bug report for all binary packages built from the same source package. For example, you may want all bugs in libreoffice. If so, go to http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=libreoffice (note the src: prefix).
If you got a bug report number you can go directly to that report with a URL of the form http://bugs.debian.org/12345.
At the top of the overview pages is a list of categories of bug reports (by severity and status). At the bottom, you'll find a form that lets you widen or narrow your search by keywords or properties of the bugs like their status or age.
Also note that in the main section of the overview page, just after each bug number, is a cryptic list of characters and symbols between two square brackets. Hovering over one of these symbols gives a tooltip that explains what it means and if you click on them, a pop-up appears with some further information about the bug report at hand.
That's a short introduction to the web interface. Don't forget that it's only able to retrieve info about the bugs, so feel free to click around - nothing bad can happen!
Reporting bug reports: reportbug
For bug reporting you need an email client, or much more conveniently, you can use the reportbug tool. reportbug is mainly a textbased tool (but there are two graphical interfaces: urwid and GTK+ based). There is also reportbug-ng, which is a completely different tool, also with a graphical interface, which aims to do the same job.
Even if you don't have a local MTA, reportbug is still extremely useful because of its --template option. This will help you produce information for the bug report that the package maintainer would otherwise request anyway, such as the versions of the package with the bug and the packages on which it depends.
To try it out, just run in a terminal:
reportbug --template package
with a package name that you have installed. Don't worry, it doesn't do anything harmful: it will just spit out some lines of text.
Looking at the output, you will see several important bits that should appear on any bug report email. Firstly, there's the address that we're sending the report to:
To: Debian Bug Tracking System <email@example.com>
The firstname.lastname@example.org address is where new bugreports are mailed to. Obviously in your bug email you should set a helpful and descriptive bug title that gives the package maintainer a first idea of what the problem is (the default Subject: none is not hugely helpful!)
Then there is another block that starts off with Package:, and has Version: and Severity: lines:
The Package: and Version: lines should be put into the first lines of your bug report, into the mail body, where you usually would start off with Dear friend,.
The Severity: line is optional, you can leave it off if it is a normal bug report. The severity can have different fixed levels, from grave, critical, serious, over important and normal to minor and wishlist.
The first three (grave, critical and serious) are considered release-critical and define a special group of bug reports. If in doubt, do not use them unless you are sure what they mean: some people might react quite jumpily if they are used and the bug report isn't really that severe. I will mention the special meaning of release critical bug reports a bit later.
wishlist is the severity you should use for enhancements that you would like to see in a package. Some package maintainers might suggest to you to report them directly to upstream. Be prepared for that - even personally I consider a package maintainer to be a binding chain and proxy between our Debian users and Upstream developers.
Finally, just again as reminder, try to be as descriptive not only in the bug title but also in the body of the bug report. Even better, try to include a recipe to reproduce your bug.
For a more systematic description of how to report bugs see http://www.debian.org/Bugs/Reporting, which also gives more information about pseudo-header fields and what should appear in the body of the bug report.
Tweaking bug reports: email@example.com
For tweaking bug reports, there is the firstname.lastname@example.org mail address. The whole bug tracking system is open to anyone, as is this mail address. This means that everyone is technically able to tweak any bug report. The control address is where the fun starts. It also works like the submit address on the first lines of the bug report.
The documentation for the control mail address can be found on http://www.debian.org/Bugs/server-control
The syntax is usually:
command bugnumber arguments
and the amount of the arguments vary by command.
So with retitle:
retitle 12345 new-title
you set the title of the bug report 12345 to new-title.
Don't worry, you can't do it for that bugnumber: that bug is archived already. You can only tweak bug reports that haven't already been archived.
A frequently used command is reassign, which states that a bug report belongs in a different package. This command takes a second argument after the package name: a version number. If you know which version of the other package is affected by the bug, you should add it so that version tracking can continue to work. I will explain version tracking a bit later, and did dig up some examples where you can see how it works.
The tag command helps to classify the bugs. Actually on submitting a bug report you can also add Tags: to the fields in the pseudo-header of the submission and already set specific tags for a bug report.
Some of the tags that are more regularly used are:
patch: when you add a fix for the problem with your mail.
moreinfo and unreproducible: when package maintainers have trouble understanding or reproducing the issue.
security: when the bug is about a security issue.
The full list of tags can be seen at http://www.debian.org/Bugs/Developer#tags.
Mail to the control address is stored in the BTS but isn't sent out anywhere else, so usually you see control mails have a Cc to email@example.com. Such mails get copied to the package maintainer (and other people subscribed to that particular bug report).
If you want to subscribe to a specific bug report, simply send a mail to firstname.lastname@example.org. You will receive an email which you have to confirm and then from then on you'll receive all emails sent to that bug report. You can also subscribe to all bug reports of a specific package through the PTS (Package Tracking System) by going to http://packages.qa.debian.org/packagename (exchange packagename with the package you want to subscribe to). In the lower left corner you'll find the subscribe form.
Of course, mail to both control@bugs and bugnumber@bugs contains both commands for the control server and information for humans. In order not to confuse the control parser with human text, there is a special command, thanks, that you might have noticed after the control commands. This tell the parser to stop parsing the mail from then on. Please be nice to the parser and use thanks to end your control messages.
Also, please notice that I always just said that mails to bugnumber@bugs are sent to the package maintainer (and subscribers of the bug). Those mails are NOT sent to the person who originally reported the bug! This is something that might change in the future, but for the time being you either have to dig up the submitter from the bug report and add it explicitly to the copies or use another convenience mail address: email@example.com.
What actually is this version tracking?
BTS keeps track of in which version a bug was closed, which releases it affects and the likes. That's why the Version: field in the pseudo header of the bug submission is very important. Otherwise the BTS might think the bug affects every single version of the package.
And this is also the place where I come back to the special bug group of release-critical bugs that I mentioned earlier. Because bug reports can get archived after 28 days if they fulfill some criteria: usually bugs have to get fixed both in unstable and in testing to get archived.
Of course only if they affect both releases - a bug report that affects only unstable but not testing (because of the found version) can get archived right ahead - if it's built on all architectures.
So, the affected distributions is one criterion, the affected architectures the other. If both criteria are solved and fixed, the timer starts.
Bug reports can get closed in several ways. The most common is through a package upload that contains a closes: #12345 in the changelog. When the package is accepted into the archive this triggers a mail to firstname.lastname@example.org with Version: 1.2.3 in the first line of the mail. This can obviously also be done manually, so if one does send a mail to bugnumber-done@bugs with a Version: header field that also claims the bug report to be fixed in that version.
If the bug report is a non-issue (like, a false report) then the Version: line should be NOT added to the mail.
This difference is needed for the BTS to be able to distinguish bugs fixed in a specific version and bugs that aren't really bugs.
The later will start right ahead with the 28 day period. The former will only start when the package in that version is in sync in unstable on all architectures and also in testing (if the bug affects testing).
I still haven't touched the release critical bug reports that are thrown around anywhere.
release-critical bug reports will ALSO have to be fixed for stable to start their archival process. So even when a release critical bug report got closed in unstable, did move over to testing and is in sync on all architectures, it will NOT get archived as long as the version tracking still thinks it affects stable.
The BTS web interface has a very helpful feature for all of this: The version graph. You might have noticed it already in some individual bug reports, it's in the upper right-hand corner. It consists of several boxes: red round ones and green square ones. The green ones are those of fixed versions, the red ones are those versions affected.
Like mentioned earlier, feel free to click around - this includes clicking on the version graphs. This will immensely enhance readability of them.
Let's take a look at an easy bug graph:
This graph is really simple, there can be very complex graphs with several branches around. You see on top the green box and also the releases mentioned (testing, unstable) and below the red one (stable). On the left side you see the Severity: grave. Like mentioned, this is a release critical bug report. This is the reason why this bug report isn't archived yet.
From reading the bug report it seems to be wrongly affecting stable: icedove 3 is not part of stable, so this bug report isn't of grave severity for stable. But given that one can't set severity by release this is where the also former mentioned bug tags come into play.
There are tags for the distributions. During my work on reducing the stable release-critical bug count I stumbled upon a lot of such bug reports. So tagging this bug report with
tag 598274 + squeeze sid
will mark it as _not_ affect Lenny.
If a bug report has a release tag attached to it the BTS considers the bugs to only affect the given releases. If you have a local MTA and did set the DEBEMAIL environment variable like I do, there is an extremely helpful tool in the devscripts package: it's called bts - guess what it's for.
bts is a commandline client to the BTS, and I just sent a control mail about this issue with submitting this at the commandline:
bts tag 598274 + squeeze sid '# not relevant for stable'
So when reading further down the bug report it seems that the fixed version 0.7.3-3 was set wrongly, and we should remove it:
bts notfound 598274 0.7.3-3
Actually such things can even be chained and combined in the bts tool, separated with dots.
This is especially useful when doing a lot of different things at once, it does only produce one email then and not several.
If you reload the bug page you will see the Tags are already set. Nothing else seem to have changed, has it? Something has changed: if you click on icedove-bidiui on the top to get to the overview page of the bugs for that package, and then click on the [G|u|☺] part in the bug short description, you will see that the bug can get archived in 28 days! Hooray, we just managed to close a stable release critical bug, live here and now
Take a look at this bug:
Actually this bug looks a bit strange. The initial mail does contain a Version: header field, but there is no graph at all, and no version information in the summary at the top. Let's scroll down and look what happened.
Right after the initial mail you will notice two short snippets of Bug reassigned and especially Bug No longer marked as found in versions. Ahah! It lost its version information because of a reassign! I mentioned earlier that a reassign can actually take an additional argument which is a version number. Unfortunately this hasn't been used here.
Let's check. Now that's even more funny. The bug was reassigned from open-vm-dkms to open-vm-tools. Aren't they related? If one investigates further you will find out that one is the source package name and the other is a binary built from this very source. So, actually, they should have the same version information, right? So what to do now?
bts found 606327 2010.06.16-268169-3 '# re-add version information lost in reassign'
We will have to wait a bit for that to happen. After waiting if we reload the page, we will see that a bug graph appeared, and it contains (testing, unstable) only. The bug doesn't affect stable anymore. Second stable RC squashed!
Let's check the next bugreport.
This bug graph is just a single version. The package doesn't seem to have got uploaded since Lenny was released!
So the BTS has no chance at all just by version information anyway to distinct whether this is affecting stable or not. It needs again the help of the release tags. When reading the first line of the bug report right ahead, after upgrade to squeeze, it hints in that it doesn't really affect stable.
So we are doing tagging it with + squeeze sid again.
After waiting a while, we see that the version graph at the bug page hasn't changed at all. That's correct, but the release tags are set, so it isn't considered affecting stable anymore. Third stable RC squashed!
Now a a bit more tricky issue, these were all simple cases.
Let's see this bug report:
This bug is marked as closed since February! That's definitely longer ago than 28 days! What's going on?
We have a found version listed, and a fixed version in the information on the top left. And we have a completely red graph. Where is the green spot? Like mentioned, you can click on the graph. This doesn't give more information yet, but you can expand the graph: [Don't collapse].
Fixed in version 2.28.0-1. Can anyone find 2.28.0-1 in that graph? I don't believe that I'm that blind, and I guess you all can confirm that that version isn't in the graph. So what happened here? As can be seen the bug wasn't closed with an upload but with a plain mail.
It can easily happen that someone fumbles with the version in there, and this seems to have been the case here. Because the PTS doesn't know about that version in its history neither: http://packages.qa.debian.org/g/gnome-media.html
We just need to adjust the version information. We choose the conservative approach and mark it as fixed in 2.28.1-1 which was the next uploaded version after which it claimed to be fixed:
bts notfound 507360 2.28.0-1 '# fixing version information' . found 507360 2.28.1-1
Similar issue with 418597, it needs also digging around the proper fixed version.
Actually there seem to be some more mishaps in the gnome-media package so I sent to one of the package maintainers a ping to go over them to take a look.
Those aren't RC bugs, but not closed properly neither because of version tracking.
Now to some other issues: http://bugs.debian.org/src:logrotate. This package has a nice amount of already fixed versions. When one clicks on the bug tags for the additional tool tip information one sees that they are closed since … ages? Now what the heck? What's going on?
Let's check on 388608. The tool tip says Modified 1 year and 116 days ago. Wow! A fair time over 28 days, isn't it?
Let's check the bug graph.
I doubt you will be able to read it, so click it. On top, (testing, unstable) in the green box. But what the? There is another unstable in a red circle further down the road?! Now can that be, two unstable versions?
Let's check packages page: http://packages.debian.org/unstable/logrotate: if you scroll down to the end of the page you find the version information. And even in here we have a colour code: green is in sync, yellow is behind in Debian revision, and red is behind in upstream version. We can safely ignore the m68k yellow because it's an "unofficial port".
The culprit version is hurd-i386, it's 3.7.1-5 and that was also the version of the circle with (stable, unstable) in the bug graph!
So what can we do? Either find a hurd porter to get the recent version of the package built, or ask one of our nice ftp masters to remove the package on hurd-i386. This is done through report bug ftp.debian.org. report bug does one guide helpfully through a menu system for this pseudo package making it extremely easy to request even such partial removals of a package.
I usually select RoQA (Request of Quality Assurance) because the QA team is everyone, including you. Yes, it consists of everyone that cares for Debian.
Actually this package has the same problem: http://bugs.debian.org/src:distcc. I did file a hurd-i386 removal request on distcc earlier today, and we have pretty quick ftp master members, it's done already.
And if you click on the information on those bugs, they will be archived soonish.
If you wonder how I stumbled upon the examples, I used the UDD for it.
The UDD is the Ultimate Debian Database and it can be queried with whatever comes to mind.
The first is the list of still outstanding stable release critical bug reports (which nowadays can also be queried through http://udd.debian.org/bugs.cgi) by selecting Lenny on top. The later is just a summary of bug reports that got closed last year already and still aren't archived.
Questions and Answers
QUESTION: Is there a rule for the bug title?
ANSWER: In general no. Some package (or rather, pseudo-packages) do use the bug title for automatic processing and prefer special formatting inside. Usually those people are aware that it's not as easy to get that knowledge around so they don't get jumpy when you fail that.
One of these special (pseudo) package is ftp.debian.org. They have special requirement for the topic so they know what to do just by looking at the title of the bug report instead of going through the body, it's just additional information.
QUESTION: Who and how can change the Severity of the existing (previously reported) bug report?
ANSWER: This brings us to the next special mail address, email@example.com
QUESTION: How important is the "APT Policy" for a bug report ?
ANSWER: Actually, I'm not exactly sure what you mean with "APT Policy" in that respect, can you explain it a bit further? It is the first time I've heard that term, especially in connection with bug reports?
Maybe the "APT policy" line, reportbug usually adds when reporting a bug to a package (summary of apt-cache policy information).
Coming back to reportbug --template output The actual bug report should be put in between the block with Package, Version and Severity, and the rest starting off with System Information.
The System Information block helps the maintainer to dig up troubles that might be the cause of special dependencies or debconf related settings or used kernel. When the bug report itself is very detailed, these System Information usually isn't used or needed at all. But quite often some people do submit bug reports with poor information (not intentionally) and then these System Information might give a good hint in which direction to investigate. Hope this answers your question well enough.
QUESTION: On output of "reportbug --template package-name" under system information : APT policy: (500, 'stable').
ANSWER: Yes, figured that now. This is the default value that stable users will send along. People might have other repositories set in their sources.list and tweaked the preferences so that packages from a specific release are preferred to get installed. This is apt internal information - but useful (additional to the version of the package) to the package maintainers to see in what environment the bug is happening.
ANSWER: You need to use the explicit control@ mail copy, automatic parsing isn't done. From what I understood it's worked on but it might take a bit to make it reliable and not catch something it shouldn't.
QUESTION: 28 days from submission? or from last edit?
ANSWER: Answered in Tracking version Section.
QUESTION: The bug is marked as fixed in 0.7.3-3, which is also the version in stable. Why does the BTS still think it affects stable?
ANSWER: Gooood question. Actually I waited for that. See the line right above that: It is also found in the same version. Given that a bug can't be found and fixed in the same version, the BTS is doing the conservative approach and removes both parts and considers them not existing.
QUESTION: What about bug tracking system attacks, for example aimed improper closing, reopening, etc?
ANSWER: Actually some spam messages managed to send mails to -done addresses. Those are usually easily caught, and given that everything can get reverted easily it's not that troublesome. The package maintainers usually notice those and react to them, as do the BTS admins regularly.
The BTS admins also have the possibility to block some senders from working on the bug tracking system in case they deliberately do malicious things.
But being open and inviting everyone to work on bugs totally outweighs the troubles that sometimes pop up because of misuse of the control bot.
QUESTION: Shouldn't that have been (not)fixed instead of (not)found?
ANSWER: Thanks for thinking along, you are of course right. Though, I won't send another control message because actually it doesn't matter. The wrong fixed doesn't affect anything, so I leave it to not annoy the package maintainers.