Differences between revisions 7 and 29 (spanning 22 versions)
Revision 7 as of 2010-12-13 23:19:02
Size: 26459
Comment: added a screenshot
Revision 29 as of 2020-03-07 10:56:24
Size: 28468
Comment: readded the info about all the page coming from a Debian Women Training Session
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: none-~ ~-[[DebianWiki/EditorGuide#translation|Translation(s)]]: English - [[fr/HowtoUseBTS|Français]] - [[it/HowtoUseBTS|Italiano]]-~
Line 4: Line 4:

CAUTION! This tutorial is still a draft... We're working on it :-)
Line 10: Line 8:
~- This page is based on a Debian Women IRC Training Session held by Gerfried Fuchs, 09-Dec-2010 -~
Line 11: Line 11:
~- Debian Women IRC Training Session held by Gerfried Fuchs, 09-Dec-2010 -~
Line 15: Line 14:
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. 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.
Line 21: Line 20:
 * DebianPkg:reportbug, DebianPkg:bts
 * DebianPkg:reportbug, bts from the DebianPkg:devscripts package

################################
<<Anchor(QueryingBugReports)>>
################################
Line 25: Line 27:
'''The web interface''' of BTS can be founded 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:/bugs.debian.org/your@maintenance.addre.ss}}} and see all the (outstanding) bug reports in all the packages you maintain with that given email address.

 * If you on the other hand do '''report bug reports''' (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:your@addre.ss}}} to see all the bug reports that weren't fixed yet.

 * If you want to '''report a new bug''' though you should first check whether the bug has already got reported. For this, {{{http://bugs.debian.org/packagename}}} can be used as overview for all the bug reports for the given package. Please notice that this is looking only for bug reports against the binary package.

 * If you want to see a '''combined bug report 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 '''bug report 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 bug reports 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 bug report short descriptions. You can hover with your mouse over them to get a tool tip, and you can click on them to receive a pop-up with some further information about the bug report at hand.

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.
'''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://bugs.debian.org/your@maintenance.addre.ss}}} 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:your@addre.ss}}}.

 * 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!


#####################################
<<Anchor(ReportingBugReports)>>
#####################################
Line 47: Line 53:
For bug reporting you need an email client, or much more conveniently, use the DebianPkg:reportbug tool. DebianPkg:reportbug is mainly a textbased tool (but there are two graphical interfaces: urwid and GTK+ based), there is also DebianPkg: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 DebianPkg:postfix, DebianPkg:exim, or DebianPkg: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, report bug 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:
For bug reporting you need an email client, or much more conveniently, you can use the DebianPkg:reportbug tool. DebianPkg:reportbug is mainly a textbased tool (but there are two graphical interfaces: urwid and GTK+ based). There is also DebianPkg:reportbug-ng, which is a completely different tool, also with a graphical interface, which aims to do the same job.

They both work best with a local ''MTA'' (''Mail Transport Agent'') such as DebianPkg:postfix, DebianPkg:exim, or DebianPkg:ssmtp. You'll have to look elsewhere for details on how to configure them.

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:
Line 59: Line 65:
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: 
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:
Line 67: Line 73:
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 ''submit@bugs.debian.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:
Line 73: Line 79:
 * 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 ''whishlist''.

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 jumpy 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.

''whishlist'' 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.

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, 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.
 * 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.

#####################################
<<Anchor(TweakingBugReports)>>
#####################################
Line 87: Line 94:
For tweaking bug reports, there is like said the {{{control@bugs.debian.org}}} mail address. The whole bug tracking system is open to anyone, as is this mail address. This means, 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. For tweaking bug reports, there is the {{{control@bugs.debian.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.
Line 97: Line 104:
The amount of the arguments vary by command. and the amount of the arguments vary by command.
Line 107: Line 114:
Don't worry, you can't do it for that bugnumber, that bug is archived already. You can tweak only not-already archived bug reports. 

A command usually used is '''{{{reassign}}}''' to state that a bug report is 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 it is very useful and needed to add the version 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 is working. :)

The '''{{{tag}}}''' command helps to classify the bugs. Actually on submitting a bug report you can also add ''Tags: '' to the pseudo headers of the submission and already set specific tags for a bug report.
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.
Line 114: Line 121:
 * {{{patch}}}: when you add a fix for the problem with your mail
 * {{{moreinfo}}} and {{{unreproducible}}}: when package maintainers have troubles to understand the issue
 * {{{security}}}: when the bug is about a security issue, and the likes.

The list of tags can be seen on [[http://www.debian.org/Bugs/Developer#tags]].

Mails to the control address are stored in the BTS but aren't sent out anywhere special, so usually you see such control mails have ''Cc'' to ''bugnumber@bugs.debian.org''. Such mails get sent to the package maintainer (and other peoples subscribed to the address).

If you want to subscribe to a specific bug report, simply send a mail to ''bugnumber-subscribe@bugs.debian.org''. You will receive an email which you have to confirm, 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'') on {{{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.

But, if people send mails to both ''control@bugs'' and ''bugnumber@bugs'' you don't want to confuse or annoy the control parser with the text that you add for the package maintainer. There is this 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 subscribed people). Those mails are NOT sent to the person who did report the bug! This is also something that is in discussion to be changed - for the time being, you either have to dig up the submitter from the bug report and add it explicit to the copies, or use another convenience mail address: ''bugnumber-submitter@bugs.debian.org''.
 * {{{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 {{{bugnumber@bugs.debian.org}}}. 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 {{{bugnumber-subscribe@bugs.debian.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: {{{bugnumber-submitter@bugs.debian.org}}}.


#####################################
<<Anchor(VersionTracking)>>
#####################################
Line 132: Line 143:
BTS keeps track of in which version a bug was closed, which releases it affects and the likes. That's why the ''Version:'' pseudo header in 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 fulfil some criteria: usually bugs have to get fixed both in unstable and in testing to get archived.
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.
Line 140: Line 151:
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 ''12345-done@bugs.debian.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 ''-done@bugs'' with a ''Version:'' header that also claims the bug report to be fixed in that version. 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 ''12345-done@bugs.debian.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.
Line 192: Line 203:
If you reload the [[http://bugs.debian.org/598274|bug page]] you will see the Tags are already set. Nothing else seem to have changed, has it? There ''has'' something 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 :) If you reload the [[http://bugs.debian.org/598274|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 :)
Line 196: Line 207:
Take a look at [[http://bugs.debian.org/606327]]. Actually this bug looks a bit strange. The intial mail does contain a ''Version:'' header, 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 …
Take a look at this bug:

[[attachment:open-vm-dkms.png|{{attachment:open-vm-dkms.png|screenshot of web page of bug report for bug #606327 before this tutorial|width=800}}]]


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.

[[attachment:open-vm-dkms2.png|{{attachment:open-vm-dkms2.png|screenshot of the "Bug Reassigned" message in the web page of bug report #606327|width=850}}]]

Line 206: Line 226:
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! :) We will have to wait a bit for that to happen. After waiting if we reload [[http://bugs.debian.org/606327|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! :)
Line 210: Line 230:
Let's check the next bugreport: [[http://bugs.debian.org/605784]]. 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 wether this is affecting stable or not. It needs again the help of the release tags. When reading the first line of the bugreport right ahead, ''after upgrade to squeeze'', it hints in that it doesn't really affect stable.
Let's check the next bugreport.

[[attachment:nagios.png|{{attachment:nagios.png|screenshot of bug report web page of bug #605784|width=800}}]]

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.
Line 216: Line 240:
After waiting a while, we see that the version graph 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! After waiting a while, we see that the version graph at the [[http://bugs.debian.org/605784|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!
Line 223: Line 247:
Let's see [[http://bugs.debian.org/507360]] This bug is marked as closed since February! That's definitely longer ago than 28 days! What's going on! Let's see this bug report:

[[attachment:gnome-media.png|{{attachment:gnome-media.png|screenshot of webpage for bugreport for bug #507360|width=800}}]]

This bug is marked as closed since February! That's definitely longer ago than 28 days! What's going on?
Line 227: Line 255:
[[attachment:gnome-media2.png|{{attachment:gnome-media2.png|screenshot of expanded version graph for bug #507360|width=800}}]]
Line 246: Line 276:
When one clicks on the bug tags for the additional tooltip information one sees that they are closed since … ages? Now what the heck? What's going on?

Let's check on #388608. The tooltip says Modified 1 year and 116 days ago. Wow :) A fair time over 28 days, isn't it. ;)

Let's check the buggraph. 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 color code: green is in sync, yellow is behind in debian revision, and red is behind in upstream version. We can savely ignore the m68k yellow because it's an "inofficial port".
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 DebianBug: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.

[[attachment:logrotate.png|{{attachment:logrotate.png|screenshot of webpage of version graph of bug
#388608|width=800}}]]


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".
Line 256: Line 291:
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 reportbug ftp.debian.org. reportbug 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. [[attachment:logrotate2.png|{{attachment:logrotate2.png|screenshot of webpage of package logrotate with version information for all architectures|width=800}}]]

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.
Line 264: Line 301:

#####################################
<<Anchor(UDD)>>
#####################################
Line 270: Line 311:
I did set me up two pages on my alioth acount (from where everyone can query it) to track such things down: [[http://alioth.debian.org/~rhonda/]].

The first is the list of still outstanding stable release critical bugreports (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 bugreports that got closed last year already and still aren't archived.
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.


#####################################
<<Anchor(FAQ)>>
#####################################
Line 278: Line 321:
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: 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?
Line 292: Line 335:
Coming back to {{{reportbug --template}}} output :) The actual bugreport 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 bugreport itself is very detailed, these ''System Information'' usually isn't used or needed at all. But quite often some people do submit bugreports 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 pakage-name" under system information : APT policy: (500, 'stable').
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').
Line 301: Line 344:
QUESTION: Can you do all the control-server actions by using pseudo headers in an email to bugnumber@b.d.o or do you need to use control@b.d.o?

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 relieable and not catch something it shouldn't.
QUESTION: Can you do all the control-server actions by using fields in a pseudo header in an email to bugnumber@b.d.o or do you need to use control@b.d.o?

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.
Line 313: Line 356:
QUESTION: What about ''bug tracking system atacks'', for example aimed improper closing, reopenning, etc?

ANSWER: Actually some spam messages managed to send mails to -done addresses. Those are usually easily catched, and given that everything can get reverted easily it's no that troublesome. The package maintainers usually notice those and react to them, as do the BTS admins regularly.
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.
Line 319: Line 362:
But being open and inviting everyone to work on bugs totally outweights the troubles that sometimes pop up because of misuse of the control bot. 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.
Line 326: Line 369:

#####################################
<<Anchor(SeeAlso)>>
#####################################
Line 331: Line 378:

----

CategoryBugs | CategoryRedundant: merge with [[BTS]]

Translation(s): English - Français - Italiano



This page is based on a Debian Women IRC Training Session held by Gerfried Fuchs, 09-Dec-2010

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.

Requirements

Technical requirements:

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://bugs.debian.org/your@maintenance.addre.ss 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:your@addre.ss.

  • 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.

They both work best with a local MTA (Mail Transport Agent) such as postfix, exim, or ssmtp. You'll have to look elsewhere for details on how to configure them.

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 <submit@bugs.debian.org>

The submit@bugs.debian.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: control@bugs.debian.org

For tweaking bug reports, there is the control@bugs.debian.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 bugnumber@bugs.debian.org. 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 bugnumber-subscribe@bugs.debian.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: bugnumber-submitter@bugs.debian.org.

Version tracking

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 12345-done@bugs.debian.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. ;)

Example 1

Let's take a look at an easy bug graph:

screenshot of bug report for bug #598227 before this tutorial

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 :)

Example 2

Take a look at this bug:

screenshot of web page of bug report for bug #606327 before this tutorial

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.

screenshot of the "Bug Reassigned" message in the web page of bug report #606327

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! :)

Example 3

Let's check the next bugreport.

screenshot of bug report web page of bug #605784

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!

Example 4

Now a a bit more tricky issue, these were all simple cases.

Let's see this bug report:

screenshot of webpage for bugreport for bug #507360

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].

screenshot of expanded version graph for bug #507360

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.

Example 5

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.

screenshot of webpage of version graph of bug #388608

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!

screenshot of webpage of package logrotate with version information for all architectures

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. :)

UDD

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, control@bugs.debian.org

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.

QUESTION: Can you do all the control-server actions by using fields in a pseudo header in an email to bugnumber@b.d.o or do you need to use control@b.d.o?

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. :)

See also


CategoryBugs | CategoryRedundant: merge with BTS