CAUTION! This tutorial is still a draft... We're working on it
How to use the Bug Tracking System
Debian Women IRC Training Session held by Gerfried Fuchs, 09-Dec-2010
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 - actually tweaking and manipulating it can only be done via sending emails to the system.
Querying bug reports: the BTS web interface
I would like to start with the more visible representation of it: the web interface 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 helpful part of it is several redirects it offers:
If you are maintaining packages yourself, you can go to http:/firstname.lastname@example.org and see all the (outstanding) bugreports in all the packages you maintain with that given email address.
If you on the other hand do report bugreports (and I hope you do and not keep the bugs you find for yourself and get annoyed with them over time because they don't get fixed) you go to http://bugs.debian.org/from:email@example.com to see all the bugreports that weren't fixed yet.
If you want to report a new bug though you should first check wether the bug has already got reported. For this, http://bugs.debian.org/packagename can be used as overview for all the bugreports for the given package. Please notice that this is looking only for bugreports against the binary package.
If you want to see a combined bugreport for all binary packages built from the same source package, like e.g. openoffice.org you would go to http://bugs.debian.org/src:openoffice.org instead (notice the src: prefix).
If you got a bugreport number you can directly go to that report by adding it to the end of the URL, like http://bugs.debian.org/''12345''
On the overview pages you have at the top grouping of bugreports with links inside the page, and at the bottom another form which helps you to change the view with respect to different aspects.
Also please notice that on the overview page there are sometimes pretty cryptic characters next to the bugreport short descriptions. You can hover with your mouse over them to get a tooltip, and you can click on them to receive a popup with some further information about the bugreport at hand.
Alright, this is the short abstract about the web interface. Again, it's only a query interface. So feel free to click around, dig around - nothing bad can happen.
Reporting bugreports: ''reportbug''
For bug reporting you need an email client, or much more conveniently, use the reportbug tool. reportbug is a textbased tool, there is also reportbug-ng which is a graphical interface that aims to do the same job but is still a different tool.
Both do require a local MTA (Mail Transport Agent) like postfix, exim, or ssmtp. I won't go into details on how to configure them, actually it's quite helpful for some to have one locally so they can write mails on their laptop when they are offline and they get sent when they go online again.
Even though when you don't have a local MTA, reportbug still is extremely useful. Because it has a --template option. This will help you produce information for the bug report that the package maintainer would otherwise request anyway, like dependency information or similar.
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 just will spit out some lines of text.
There are several important things that will give you an idea on what to do, like where to send the email to:
To: Debian Bug Tracking System <firstname.lastname@example.org>
The submit@bugs address is where new bugreports are mailed reported at. 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.
Then there is another block that starts off with Package:, has a Version: and a Severity: line:
The Package: and Version: lines should be put into the first lines of your bugreport, 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 bugreport.
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 bugreports. If in doubt, do not use them unless you are sure what they mean, some people might react quite jumpy if they are used and the bugreport isn't really that severe. I will mention the special meaning of release critical bugreports a bit later.
wishlist is the severity 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.
So far we gone through querying for bugreports, and reporting new ones. For reporting, just again as reminder, try to be as descriptive not only in the bug title but also in the body of the bugreport, and it would be great if you could include a recipe to reproduce your bug.
About reporting bugs, this is also documented in http://www.debian.org/Bugs/Reporting so you can check it on that page.
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 formating 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 bugreport instead of going through the body, it's just additional information.
QUESTION: Who and how can change the Severity of the existing (previously reported) bugreport?
ANSWER: This brings us to the next special mail address, email@example.com