In a hospital, triage happens the instant a patient arrives through the emergency room doors. His vital signs are checked, his status assessed, and he gets sorted in amongst all the other patients waiting for treatment.
Bug triage is a lot like that because we assess bugs to determine whether or not they have enough information to be worked on and assign a priority to them as soon as possible. Without any risk of death. This page explains the different aspects of triaging.
Ubuntu receives an incredibly large number of bug reports every day through our bug tracking system. Each one of these needs to be read, assessed, and sorted so it can be fixed. This is where we could use your assistance with HelpingWithBugs. For a visual representation of the bug triage process, see these nice Flow Charts.
Every bug report is a conversation with the reporter. The first contact any reporter usually has with the Ubuntu community is through a bug triager, who tries to put together a complete bug report. It's very important that we give a good impression, so please be polite and try to use your best English.
Working on simple, untriaged bugs is a good way to get started and become acquainted with the triaging procedure since you'll have to deal with every aspect of the life cycle of a bug. The section Untriaged bugs explains where to find them.
Apport reports are bugs reported via the automated bug reporting program Apport. Reporting bugs using Apport is the preferred way of reporting a bug since it gives the developers a lot of information about the affected system. When Apport is used, less additional information is required, speeding up the whole process. You can recognize these bugs by the added list of system information in their description. Some programs have hooks for Apport, adding more information when reporting a bug. This information can usually be found in the attachments.
Apport crash reports
A considerable number of bugs reported by Apport concern program crashes which are reported semi-automatically and get pre-processed automatically by bots in the Canonical data center. These bots try to generate a fully symbolic stack trace and check for duplicates.
In Feisty and early Gutsy, those bugs were public, so that everyone could see them. However, this created a privacy problem since core dumps and stack traces could potentially contain sensitive information. Also, crash reports generate a lot of bug mail noise. With the automatic duplicate checking, a fair amount of the reported bugs are completely irrelevant for triagers.
Since Gutsy, these problems have been mitigated: bugs are filed with the "private" flag enabled, i. e. only the reporter and subscribers can see it. The reprocessing bots will subscribe the ubuntu-bugcontrol team, but without sending bug email to the team members.
Thus crash bugs differ from other bugs in two important aspects: they need to be checked for sensitive data, and there will not be any initial bug mail for them until they become public. Triagers should check the following things:
If the crash still has a CoreDump.gz attachment, then it was not possible to automatically get a fully symbolic stack trace and check for duplicates. In this case, the bug will be tagged with apport-failed-retrace. If the stack trace looks good enough, the CoreDump.gz attachment should be removed with the (edit) link in the attachment box. If the retrace failed completely, mark the bug as 'Invalid' and ask the reporter to refile the bug if the crash can be reproduced. Never mark a bug containing a Coredump.gz attachment as public.
If there is no Stacktrace.txt (retraced) attachment, then the most probable reason is that the CoreDump.gz attachment is broken. Please check with Martin Pitt (pitti in IRC, email@example.com) about the reason since he can look into log files.
Check if any of stacktrace attachments (original stacktraces, Stacktrace.txt (retraced) and ThreadStacktrace.txt (retraced)) have anything that looks like sensitive data passed as function arguments. Examples are passwords, things that look like bank account numbers, CSS keys, user names, server names, etc. If you don't find anything, you may mark the bug as public ("This report is public/private" in the top right of the bug report). This is not required though, it is fine to keep the bug private throughout its lifetime.
Except for those privacy issues, crash reports should be handled like normal bugs in terms of duplicate searching/marking, upstream forwarding, etc.
When a bug is marked as 'Confirmed' it is not fully triaged yet. This bug is very close to being marked as 'Triaged', but you need to make sure it is ready for the developers to fix. If the bug adheres to ALL of the following criteria it can be considered triaged:
- Does the bug report describe a valid bug?
Does the bug report contain enough details?
If the bug is fixable within a day, is it marked as affecting the "hundredpapercuts" project?
If bugs for the packaged are managed elsewhere, is the bug report forwarded upstream?
- Is the bug report ready to be worked on by a developer?
Only if ALL of these conditions are satisfied, you can set the status of the bug report to 'Triaged'. To do this:
- Change the "Status" field to "Triaged".
If not done yet, assign the appropriate importance.
- Click "Save changes".
In order to set bug statuses to 'Triaged' you need to be a member of the Ubuntu Bug Control team. If you are not a Bug Control member, and you find a bug you believe is ready to be marked as Triaged, then please join the #ubuntu-bugs channel on irc.freenode.net and provide a link to the report. A Bug Control member can then examine the report and, if it is ready, mark it as Triaged for you.
If the bug report is actually a feature request, there are two possibilities. If the requested enhancement is small and well-defined and/or the suggestion concerns an upstream project, the Importance of the bug should be set to 'Wishlist'. When the report is complete the status should be set to 'Triaged'. Only the members of the Ubuntu Bug Control team can do so. If you're not a member you'll have to ask someone who is to do it for you. Paste the bug number in #ubuntu-bugs and say you think the bug should be set to 'Wishlist'. Someone will notice and set it for you, although not necessarily immediately.
Bugs requesting a feature concerning upstream projects should be forwarded upstream. Forwarding upstream is explained at Forwarding Bugs Upstream.
However, if the request is abstract and/or suggesting a large change the bug should be closed as 'Invalid' while posting a message pointing the user to the appropriate upstream or to the user forums.
A canned response you can use is:
Thank you for taking the time to make Ubuntu better. Since what you submitted is not really a bug, or a problem, but rather an idea to improve Ubuntu, you are invited discuss the idea with other Ubuntu community members in the many public forums. Public discussion of ideas improves the likelihood of adoption. Thanks for taking the time to share your opinion!
A regression is a bug introduced after an update. These kind of bugs are especially important because if something breaks that used to work it interferes with the workflows of software users. These can be more obvious and painful for users than bugs. To make keeping track of regressions easier we use tags. Please make sure to use the tags when doing Triage.
A regression in a new stable release or a development release. This may be a bug in a single package or functionality lost when changing the default application.
A regression introduced by an updated package in the stable release.
A regression introduced by a package in -proposed
Used by the retracer when it finds a bug that has a similar trace to a previously closed bug.
Untriaged bugs are bugs that haven’t been touched by any triager yet. These bugs were reported and have yet to be touched since.
There are several ways to find these untouched bugs. The most commonly used method is using the BugTrackingSystem Launchpad's search functionality; you can use Advanced search to find New bugs for a specific package. Go to the source package's bugs advanced search page and look for:
Assigned to: Nobody
All untriaged bugs can be found via this link. Once a bug's status is no longer New it will no longer show up in this search.
If you want to be notified of new bugs there are several methods to do so:
Add the Launchpad Atom feed for new Ubuntu bugs to your feed aggregator
Join the #ubuntu-bugs-announce InternetRelayChat channel on irc.freenode.net.
Subscribe to the https://lists.ubuntu.com/mailman/listinfo/ubuntu-bugs mailing list [Warning: this is a high volume list that will quickly fill up your mailbox].
To start, just pick one of the recent ones and open the link in your favorite browser. Try to pick bugs that affect software or parts of the system you are familiar with yourself, as this will help you decide how complete the report is, and make it easier for you to reach the grail of reproducing the bug. If no one else has commented yet this bug could be yours!
Bug reports not in English
Bug reports should be in English as that is the most commonly used language by Ubuntu developers and bug triagers. In the event that a bug report is not received in English ask the reporter to translate their bug and any error messages that are not in English. In the event that you are concerned that the bug report is critical and needs to be translated quickly e-mail the Ubuntu translators mailing list for help in getting the bug translated.
Special types of bugs
Most bugs are code or packaging defects, but some groups within Ubuntu also use bugs for other things. Careful attention must be paid to these bugs so as not to disrupt team processes. These classes of bugs have special rules and different meanings for the statuses. They may even have different meanings depending on where Ubuntu is in its release cycle.
Unless a triager is familiar with the specific process in question, adjustments to these bugs are likely to be problematic.
Developer Process Bugs
You should generally not change bugs of this type unless working with a developer/packager.
- Bugs in this category can have subjects like:
Please merge <package> from Debian unstable (main)
Please sync <package> from Debian unstable (main)
Please remove <package> from the Ubuntu archives
Please promote <package> to <component>
Please demote <package> to <component>
- Main inclusion report (MIR)
Bugs in this category will have any of the following teams subscribed:
For packages in Universe/Multiverse, please see Sponsors Queue page for more details.
A needs-packaging bug is a subset of the Developer Process bugs above: it is not really a bug, but a request to add a new package to Ubuntu. You may find them with a subject like: [needs-packaging] <package>, or with either the description or summary requesting that a package be created. These bugs are used to track software requested for inclusion in Ubuntu. For these bugs, please:
read and follow the instructions on SponsorQueue. A summary follows:
check to see if it is already in Ubuntu (see http://packages.ubuntu.com, or run rmadison <package>): if it is already in the archives, then mark it as Invalid, and add a comment explaining your action;
if not in Ubuntu, then check Debian (see http://packages.debian.org, or run rmadison -u debian <package>). If it is in Debian, mark it as Invalid, and add a comment stating:
Packages for this software appear to exist in Debian already. Ubuntu has semi-automatic tools to sync new packages from Debian so it will most likely appear in the next Ubuntu release.
now check the Debian bug tracker or Work-Needing and Prospective Packages for an ITP (Intent To Package) or RFP (Request For Package) for this package. If you find one such request, please add an upstream bug watch for it, and continue on
- now check for the upstream licenses. If license info and upstream URL are included, add a comment with the license types and the links to them upstream; if not, and you cannot find them, please add a request for the reporter to link the licenses in;
- now, mark the bug as 'Triaged', and add the tag 'needs-packaging' to it.
Note: Not all package names are intuitive! Also use package descriptions to help guide you.
Note 2: Never set these bugs to 'Confirmed', unless you are working with a package maintainer, and have been asked to do so.
Note 3 The bug should remain on 'New', or 'Incomplete' status until all prerequisites are completed.
- If you are unsure as to whether the bug that you are looking at fits in one of these categories, feel free to ask in #ubuntu-bugs or #ubuntu-motu on irc.freenode.net.
The SecurityTeam uses a similar but slightly different process for Triaging bugs. If you think a bug may be a security issue or are triaging a bug flagged as a security issue, please be sure to read SecurityTeam/BugTriage before proceeding.
Translation bugs and Launchpad integration
The Ubuntu Translations team has a separate Launchpad project for keeping track of all translation bugs. Launchpad integration is also tracked by this project.
All translation and Launchpad integration bugs should have a task against the ubuntu-translations project. If a translation bug doesn't have such a task, add one:
- Click on the 'Also affects project' link, which can be above the bug description;
If necessary click the 'Choose another project' link between the parentheses after the project name, when that project name is not Ubuntu Translations;
- Enter 'ubuntu-translations' in the project name box and press 'Continue';
If the bug is a translation error, the 'ubuntu-translations' task should be assigned to the proper translation team; ubuntu-l10n-LC, where LC should be replaced with the language code according to the ISO 639-2 standard, or ISO 639-3 for languages that are not in the previous standard.
Apart from opening the 'ubuntu-translations' task to let the Translations team know the bug exists the bug should be handled like any bug. When its status in the 'ubuntu' project is set to 'Triaged' they know the report is ready for them to work on.
Below are some common actions you will perform while Triaging. The Launchpad Greasemonkey scripts can be a great time-saver while performing the below actions!
Please note that some teams have their own policies on triaging, see:
The 'Confirmed' status is used when it is certain the bug exists. If the bug adheres to ANY of the following criteria it can be considered confirmed:
- Is there a patch that claims to fix the bug?
Are there sufficient log files and crash dumps, as outlined in DebuggingProcedures?
- Can you reproduce the bug yourself?
- Does another distribution have a complete and confirmed bug?
- Does the upstream author have a complete and confirmed bug?
If ANY of these conditions are satisfied and you are not the original reporter, you can Confirm the report. To do this:
- Change the "Status" field to "Confirmed".
Assign the appropriate importance.
- Click "Save changes".
Do not be worried if a bug you have confirmed, which cannot be sent upstream stays 'Confirmed' for a very long time. Ubuntu has many, many bugs and the developers will look at confirmed bugs first.
The 'Triaged' status is used to show you are done with triaging the bug. Only members of the Ubuntu Bug Control team can set this status. Only set this status if the cause of the bug has been found and the developers can start fixing the problem right away.
Forwarding bugs upstream is an important part of being a triager. Without telling them, upstream developers might never know of the bug you've been triaging so studiously.
Bugs should be forward upstream when:
- the Ubuntu bug is Confirmed or Triaged, and
- the issue is not due to packaging or a Debian/Ubuntu patch.
Please keep in mind that you will be representing Ubuntu upstream. Try to leave a good impression. A good practice is to mention the original reporter of the bug and provide a link to the original bug report. It's often greatly appreciated if you link to the most important attachments and explain what they are.
Before writing a whole new bug report you should look for the problem you're reporting to prevent duplicates. If you find a duplicate leave a comment mentioning the Ubuntu bug and link to it. When there are no duplicates to be found you can create a new one.
Now you should link the upstream bug to the Ubuntu bug in Launchpad so we can keep track of its status. To do this:
- Click "Also affects project"
- If necessary, search for and pick the right project
- Choose the "I have the URL for the upstream bug:" option and paste the URL for the upstream bug in the appropriate field
- Click "Add to Bug Report"
Launchpad tracks the upstream bug and warns the subscribers to the Ubuntu bug when the status upstream has been changed.
The page Bugs/Upstream provides more details on how to report bugs in various upstream bug trackers.
Marking a bug as requiring forwarding
If you find a bug that needs forwarding, it is best to forward it immediately. However, if you are running short on time, you can still mark the bug as needing to be forwarded. To do this:
Open an upstream task (you click on "Also affects project"), but do not assign a bug watch by selecting the option "I just want to register that it is upstream right now; I don't have any way to link it." and press "Add to Bug Report". (Mind the wording, there is a bug filed against LP bug #353097)
- This will mark the bug as "needs forwarding"
- You can search for those bugs in the "Advanced Search" by selecting the "Show only bugs that need to be forwarded to an upstream bugtracker" option.
Many of the reports filed against Ubuntu are actually duplicates of bugs already reported. This can happen after a high profile bug has been introduced into Ubuntu, causing a lot of users to report it. Other times, reporters don't know how to check if the same bug has already been filed, or it is hard for them to determine if their bug is the same as another. Finding these duplicate bugs and aggregating information in one bug report is a very valuable contribution.
Bugs are duplicates when they have the same root cause. Determining this is a skill that you'll pick up as you become more familiar with a particular package or subsystem. Bugs are not necessarily duplicates if they have the same effects. For example, many different bugs can cause X not to start. Determining which bug a particular report refers to is part of triaging. If in doubt, ask for a second opinion. It is probably also sensible to ask the reporter to take look at the possible duplicate and to help with the decision. Reporters are normally interested in helping with their own bug reports!
When you first look at a new bug, try to find an existing bug in the system that describes the new one. Here's how:
Click the "List open bugs" link at the bottom of the bug page or
- Click the "Bugs" tab at the top of the page
- Both ways will produce a list of bugs about the same package
- Look for bugs with similar descriptions or related titles.
- If they describe the same root cause, decide which report should be the primary one. This should be the one that's the most understandable and contains the most information, not necessarily the oldest (lowest numbered) bug.
For the other report, add a comment like this standard reply
Include: Nothing found for "^== A duplicate ==$"!
When you update one of these responses, you should also update the response used by the Firefox extension. These responses can be found in the bazaar branch lp:ubuntu-bugcontrol-tools in the file gm-xml-files/bugsquad-replies.xml. To check out a branch, use
bzr branch lp:ubuntu-bugcontrol-tools
Only members of bug-control can commit to this branch. But you can submit a merge proposal, Brian Murray will review/merge it (see this email message), and they can be used when replying to a bug report if merged.
Not described well
Thank you for taking the time to report this bug and helping to make Ubuntu better. Unfortunately, we cannot work on this bug because your description didn't include enough information. You may find it helpful to read "How to report bugs effectively" http://www.chiark.greenend.org.uk/~sgtatham/bugs.html. We'd be grateful if you would then provide a more complete description of the problem.
We have instructions on debugging some types of problems at http://wiki.ubuntu.com/DebuggingProcedures
At a minimum, we need:
1. the specific steps or actions you took that caused you to encounter the problem,
2. the behavior you expected, and
3. the behavior you actually encountered (in as much detail as possible).
Missing Steps to Recreate Bug
Thank you for taking the time to report this bug and helping to make Ubuntu better. Please answer these questions:
* Is this reproducible?
* If so, what specific steps should we take to recreate this bug?
This will help us to find and resolve the problem.
Missing Apport Information
Thank you for taking the time to report this bug and helping to make Ubuntu better. Please execute the following command, as it will automatically gather debugging information, in a terminal:
When reporting bugs in the future please use apport by using 'ubuntu-bug' and the name of the package affected. You can learn more about this functionality at https://wiki.ubuntu.com/ReportingBugs.
Package or domain specific questions
The following packages or type of bugs require the specific debugging information:
- Then click the "Mark as Duplicate" link at the top right of the bug report page, and enter the number of the primary bug.
By default, searches in Launchpad and mentioned above will only look at Open bugs. It may also be worthwhile to go through the list of Invalid and Won't Fix bugs which you can look for by using an "Advanced Search". There is also a standardized tag for bugs likely to have lots of duplicates -- metabug.
When marking a bug report as a duplicate of another (master) bug report, please also check whether the master bug report is marked as private. If so, the master bug report might not be visible to the current bug reporter. When the parent bug is indeed marked as private please check why it is so. If it's only private because apport makes all bugs private by default, but the coredump has been removed and none of the apport attachments contain anything private, it may be made public. If it does contain confidential information, the bug should remain private and it is better to search for another bug which could be safely marked as the master bug. For any guidance regarding the private status of a master bug and marking another bug as a duplicate of it, please ask in the IRC Channel of the Bug Squad (#ubuntu-bugs). For more information on private Apport bugs, have a look at the Apport crash reports section.
Improving a bug report
Only valid and well described bugs can be processed efficiently and swiftly by the developers. A small guide at Bugs/Improving helps with handing over a good bug to the developers when setting the status 'Triaged'.
Converting a bug report to a question
Some bug reporters aren't actually reporting a bug but rather are looking for support with using Ubuntu. These bug reports should be converted to questions so that they will appear in the Launchpad answer tracker and can be answered there. Telling whether or not a bug report is actually a support request is subjective but these guidelines may help you determine which is which.
- Is the reporter looking for help to accomplish a task?
- Installing printer drivers for a printer is a good example of this
- Is the reporter missing a package to accomplish a task?
- Missing codecs to watch DVDs is a good example of this
- Is the bug report in a foreign language?
- Has the reporter misconfigured their system?
Mangled lines in /etc/apt/sources.list
Sometimes, you will have to invalidate a bug report. This may be because the problem is not reproducible, or the program was designed to behave a certain way.
There will be a few bug reporters who never get back to you and there is not enough information for the bug to be worked on. You do not need to invalidate these bugs -- bugs in incomplete status without a response will be automatically expired in 60 days.
For the other (i.e., those not waiting for a response from the reporter), the best thing to do here is to politely decline the report while thanking the user for submitting it. There are some useful Bugs/Responses that you can use in these cases.
There is no need to reject bugs that are already marked as a duplicate of another bug. Doing so creates bug mail noise as every subscriber of the duplicate bug and the master bug will receive e-mail that the status of the bug changed from something to Invalid.
Status and importance
If in doubt, the maintainer (or the one working on the bug) should change the Status and Importance. It usually reflects the status of this work or reflects how the bug fits into her/his working time.
Looking through your bugs
Perhaps you want to look at a list of bugs you are working on to see if anyone has replied and to make sure you haven't forgotten one.
A good way to get a list of these bugs is to look at your related bugs. This can be found in your "Bugs" page at Launchpad:
You can see you subscribed bugs at https://bugs.launchpad.net/~/+subscribedbugs, or the bugs you've commented on at https://bugs.launchpad.net/~/+commentedbugs. Links to both are available at your main "Bugs" page.
You should go through your bugs fairly often, maybe once a week, to make sure you haven't missed anything. This includes bugs you have reported upstream. If there is an important fact from an upstream bug you should add it to the Ubuntu bug report.