Bug reporting etiquette

Thank you for reading this article. This will guide you on how best to present your bug report so that it gets addressed as soon as possible. While this is targeted to the new bug reporter, experienced reporters would find these tips invaluable in getting their bugs looked at by a developer and ultimately fixed:

Before filing any hardware related reports on Launchpad, please update your BIOS, and hardware firmware (CF card readers, SSDs, USB 3.0 controllers, DVD/CD drives, etc.) to the newest available from your vendor. Outdated and buggy BIOS and firmware is a common cause of a variety of hardware issues (ex. freezing after lightDM login, intermittent wireless, suspend not working, certain keys on keyboard not working correctly, card readers not working, and kernel panics after plugging USB drive in). Also, please don't make the invalid argument that because it works in Windows, but doesn't in linux, this isn't caused by an outdated BIOS. This is due to how buggy BIOS problems may manifest themselves in linux, but not in Windows. As well, because BIOS vendors typically test to Windows only and make release notes commenting on results to it, it wouldn't advise on if a problem in linux is resolved by it. Hence, one should update anyways, even if your problem isn't specifically mentioned. In addition, BIOS updates are for collateral damage avoidance. For more about BIOS updates, please see here.

Please do not claim because you or someone else filed a bug report upstream or downstream (which is publicly viewable, and has no restrictions on who can file) you are somehow exempt from providing the information a developer or triager requested. You are being asked for this information so that it would provide more information on how to fix the problem.

Please do not speculate on what you think is or isn't a duplicate report (ex. I googled around and found bug report...). This is largely unhelpful as it tends not to be a duplicate, and already has been or easily done by triagers and developers. Instead, if you are the original reporter, ensuring the report has all the requested testing information performed would be the fastest way to ensure your bug is resolved as soon as possible. If you are not the original reporter, it's best to file a new report, so that necessary debugging attachments are reviewed. It is a common misconception that filing a potential duplicate report is wasteful. Filing potential duplicates isn't wasteful, and is actually preferred to ease triaging.

Please do not quote Wikipedia and other non-primary resource information as fact on Launchpad.

Many Linux package, hardware, and other non-user space bugs are hardware dependent on both the hardware itself, and what other hardware the problematic hardware is connected to. The rule of thumb is one report, per person, per hardware combination, per bug. For more on this please see here, and further below in this article. As well, please do not post comments to another person's report, claiming you have the same problem, because you have the same hardware, or same computer model. Instead, please file a separate report, and make comments there. This is because no one can verify if you would have the same problem or not, because your hardware can not be analyzed.

Please do not complain because someone sent what one perceives to be a automated or "canned" response. If the response is asking you to do something that you have't done (ex. test the latest development release, file a new report, etc.) do it, as it would get you closer to having your bug fixed. Complaining about this is inconsiderate of the Ubuntu triagers and developers who are saving time in comparison to hand typing every single character in an e-mail that goes out their inbox.

For bugs in the Linux (Ubuntu) package, unless the upstream maintainer or kernel developer notes otherwise, if a new mainline kernel comes out, and you haven't tested with it, you run the strong risk of it not being attended to upstream.

Please do not solicit non-original reporters to post comments, attachments, etc.

Please do not post comments such as “Me too!”, “+1”, “bump”, “same here”, etc., as it is largely unhelpful, produces spammy e-mail traffic to everyone subscribed to the report, and quite often turns out not to be the same root cause. Instead, please follow the below mentioned procedures.

If a triager or developer asks you for some information on reproducing or testing, please do make them dumpster dive by just posting a URL, or saying you already did something in some other report. Instead, put the full reproduction or testing results into the report itself, and if you have to, then post the link.

Please do not stack multiple issues into one report. For example, jamming suspend and hibernate into one report, reporting multiple hotkey problems into one report (ex. Fn+F3 doesn't turn off my laptop WiFi, Fn+Right doesn't turn the brightness on my backlight down, my brightness settings are not remembered after reboot, etc.). Please make one report for each individual problem.

Please do not complain about how long it takes to fix a bug, the severity of your bug is high so it should be fixed immediately, “I cannot believe it’s not fixed…”, XYZ person(s) do not care about fixing bugs, etc. Especially, if you have not followed the directions mentioned in this article, let alone contributed code upstream. This type of behavior is unconstructive, irritating to others who read your e-mail, and spammy. We all want to see every bug fixed as soon as possible! Naturally, bugs being fixed is limited to reproducibility and clarity of the bug report, the actual impact the bug has on the community, and available developer resources.

Please keep the bug objective as possible. It is desired for you to provide a fact based, technical impact statement on you, your environment, and the potential or actual impact on the community at large.

Please provide all relevant information from https://wiki.ubuntu.com/DebuggingProcedures when you first report your bug. This is one of the top reasons why bugs do not get marked Triaged, as the minimum requirements for dealing with the problem by a developer are not provided.

If a triager or developer asks you to provide information, please avoid arguing with them and just provide the information as requested. This is due to how not everyone has access to the hardware you are reporting against, so having you provide the information helps eliminate the difficulty in fixing your bug. If you have a strong disagreement with what a triager or developer is asking of you, please resolve it with them via personal message, instead of turning a bug development report into a “let’s talk about talking about the problem” report. The Ubuntu community takes a favor to objective, technical discourse.

Please do not report bugs about software in PPAs on Launchpad. This is because software in PPAs are not provided by the official Ubuntu repositories. Instead, the PPA homepage would have a contact point and preference of the PPA provider. The exception is LibreOffice as per this mail, as LibreOffice is too big to be tracked via email: as described in the mail, file a bug on Launchpad with tag ppa.

Please do not add project tasks to bug reports that are invalid because they are not supported. For example, if you were using the LibreOffice PPA and reported a bug against the package libreoffice (Ubuntu), which would be marked Status Invalid, please do not add the Launchpad Project df-libreoffice to the report, or change the package libreoffice (Ubuntu) to the project df-libreoffice. The purposes of adding the upstream project to a report is to track valid bugs in Ubuntu that are valid upstream, and may have been reported upstream, not to start another upstream bug tracker.

When posting new comments to a report, please do not include every past comment made, as doing so makes it onerous to read a report, and is wasteful. Instead just make your new comment, or just include the relevant portion of a previous comment you are responding to.

Many of the triagers and developers who are providing support to you, are volunteers doing so out of altruism. Please keep this in mind when making your comments.

How to report bugs

Ubuntu uses Launchpad to keep track of bugs and their fixes. This page will guide you through the steps required to file a good and detailed report.

Create a Launchpad account

If you don’t already have one - you need to create a Launchpad account. This will allow you to file new bugs and comment on existing ones.

Determine if the bug is really a bug

You should not file a bug if you are:

Warning /!\ If you want to file a translation or misspelling bug, follow the instructions here.

Make sure the bug hasn’t already been reported

First, check the release notes for your version of Ubuntu:

Hardware driver bugs (e.g. sound, Linux kernel, X.Org, and Nvidia / AMD proprietary drivers)

You are not the original reporter

  • Please open a new report instead of adding debugging information, attachments, apport-collect’ing, or “Me too!” comments on what may appear to be a similar bug. Chances are that your hardware does not match the existing bug’s hardware, so your bug and comments will not be addressed. As well, unless asked of you by a developer or triager, please do not mark your bug a duplicate of another reporter's bug.

  • Please do not assume because you have the same desktop or laptop model line as another original reporter’s bug report, that your problem is the same. Frequently, computer vendors use different parts under the hood within the same model line.
  • Regarding peripherals, please do not assume because you have the same peripheral, and similar problems, it is the same bug. Please file a new bug report.

You are the original reporter

If you are the original reporter, here are the ways to maximize the speed with which your bug is fixed:

Desktop Applications

For desktop applications, please make sure it has not already been reported by searching through existing bugs. If you find an already reported bug that is exactly like the problem you have, please feel free to add this information to the existing report, rather than opening a new one. However, if you have any doubt as to it being the same or not, please file a separate report.

Back to top

Reporting a Bug

Reporting an application crash

Please report an application crash via the methods outlined below and at https://wiki.ubuntu.com/DebuggingProgramCrash.

Development release

If an application crashes, and you're using a development release, Apport will start automatically, raising an appropriate bug report for you to complete in Launchpad. This report is subsequently processed by Apport Retracing Service, in order to provide developers with debugging information that make it easier to fix the problem.

Stable release

Apport may come disabled by default. To enable it, edit the file:

/etc/default/apport

and change:

enabled=0

to:

enabled=1

Warning /!\ Even when enabled, apport will not upload crash reports to Launchpad for a stable release (see bug #994921). Instead, crash reports are uploaded to http://errors.ubuntu.com. To file a report on Launchpad anyway, one may open the following file via a command line:

gksudo gedit /etc/apport/crashdb.conf

and change:

'problem_types': ['Bug', 'Package'],

to:

# 'problem_types': ['Bug', 'Package'],

Save, close, and try to file the crash report again via:

ubuntu-bug /var/crash/_my_crash_report.crash

Warning /!\ apport will appear to upload a crash report, but only actually does so if whoopsie is installed. Whoopsie is installed by default for users of ubuntu-desktop, but for users of alternative desktops, or for server users, whoopsie has to be installed manually with apt-get install whoopsie. See bug #1001630 for details.

System crash

If your system lockups up, freezes, logs you out, etc., then this is not an application crash, but a system crash. Please see below, and consult the following article for these types of problems https://help.ubuntu.com/community/DebuggingSystemCrash.

Non-crash hardware and desktop application bugs

The method for reporting bugs in Ubuntu is by using the tool “ubuntu-bug”, otherwise known as Apport. When reporting a bug, you must tell Apport which program or package is at fault.

Collecting information from a specific package

Press Alt+F2 to open the “Run Command” screen:

Filing a bug with the “Run Command” screen

Then, type ubuntu-bug <package name> and press Enter. If you’re not sure which package has the problem, refer to the instructions for finding the right package.

Collecting information about a program with a window open

If you want to file a bug about an application but you don't know what that application's package name is, if it has an open window you are in luck.

In a terminal execute the command 'ubuntu-bug -w'.

terminal with ubuntu-bug -w

After you close the dialog the next window that you click on will have a problem report created for the package that created the window.

Collecting information from a currently running program

To file a bug against a program that is currently running, open the System Monitor application and find the ID of the process.

System Monitor Processes tab

Then type "ubuntu-bug " followed by the process ID into the “Run Command” screen.

Filing a bug with the “Run Command” screen and a process ID

Filing a general bug against no particular package

If you’re not sure which package is affected by the bug, type ubuntu-bug in the “Run Command” screen and press Enter. This will guide you through a series of questions to gather more information about the bug and help you assign it to the appropriate package.

Back to top

Complete the bug report filing process

After running one of the above commands, Apport (the Ubuntu bug reporter) will gather information about the bug.

Apport collecting information about the bug

A window will then pop up, asking you if you want to report the bug. Click "Send Report" if you wish to proceed, or click "Content of the report" if you want to review the information Apport collected.

Apport asking you to send the report

Apport will then upload the problem information to Launchpad, and a new browser window will then open to inform you that the bug report is being processed.

Apport uploading the problem information

Launchpad processing the bug report data

After the bug report data has been processed, a new page will open that will ask you for the bug report's title. The bug title will appear in all bug listings so make sure it represents the bug well. When you're done, click "Next".

Launchpad asking for a bug title

A search will then occur based on the title you gave to the bug report, and will show potentially similar ones. If one of these seems to be the exact bug you're reporting, click its title, then "Yes, this is the bug I'm trying to report". If not, click "No, I need to report a new bug".

Launchpad search results about the bug title

Launchpad will then ask you for further information. It's important that you specify three things:

  1. What you expected to happen
  2. What actually happened
  3. If possible, a minimal series of steps necessary to make it happen, where step 1 is "start the program"

Fill in the description field with as much information as you can, it is better to have too much information in the description than not enough.

Launchpad asking for further information

At then bottom of the page, there are some extra options you can use to make your bug report more complete:

  • This bug is a security vulnerability: Please check this only if your bug report describes a behaviour that could be exploited to compromise your security or safety, as well as cause issues such as identity theft or "hi-jacking".

  • Tags: You can add here tags that pertain to your bug report. The predefined values should be left alone.

  • Include an attachment: Using this option, you can add supporting attachments to explain or help others reproduce the bug. This might include a screenshot, a video capture of the problem or a sample document that triggers the fault. If necessary, additional attachments can be added after the bug is reported via Add a comment/attachment at the bottom of the page. Please check https://wiki.ubuntu.com/DebuggingProcedures for anything further information to provide. It is vital for developers to get this information, as it contains the minimum requirement information necessary for a developer to begin working on your bug.

    • Please note that if one files a bug against the linux kernel package, you do not need to add as an attachment the terminal command:

lspci -vvnn
lspci -vnvn

This is due to how Launchpad automatically generates this as an additional attachment.

Launchpad presenting extra options

When you're done, click "Submit bug report".

Tips and tricks

Filing bugs when off-line

In the event that you have an issue with your Internet connection or want to file a bug for another system you can still do this using apport.

First, on the target system, gather the information in a file:

  • For a bug report about a system crash:
    apport-cli -p <package name> --save bug.crash

  • For a bug report about any other issue:
    apport-cli -f -p <package name> --save bug.apport

You will need to answer a few questions, which will vary depending on which package the bug report is about. Relevant system information, including the package name, is then saved on the target system, in the current directory. The extension indicates if it is a crash report or another kind of report. If you decide to rename the report file, please keep the .apport or .crash extension.

When the file is ready, copy it to the system you intend to use for filing the report. There you can then file the report:

  • ubuntu-bug -c <apport_file.extension>

Warning /!\ 'ubuntu-bug -c x.crash' does not work for crash reports from stable Ubuntu releases (see note about stable releases above).

If this is to be added to an existing bug report, also use the -u option:

  • ubuntu-bug -c <apport_file.extension> -u <bug number>

You will need to answer a few questions, and a web browser will be launched to complete the bug report. Please do not attach the .apport or .crash file to the report, as this is not the same as performing the above mentioned steps.

Filing bugs at Launchpad.net

If for some reason you cannot file a bug using the Apport tool you can file one via Launchpad's own bug report form. When doing so it is best if you have determined which package it should be filed against. Read 'finding the right package' for guidance or use Launchpad's package search feature. We don't recommend this method for most bug reports because they will likely be missing crucial information, use ubuntu-bug if you can!

To file a bug against a specific package you can also use a URL like the following:

  • http://bugs.launchpad.net/ubuntu/+source/PACKAGENAME/+filebug?no-redirect

where PACKAGENAME is the name of the source package about which you want to file the bug report.

In the event that you want to request a piece of software be packaged for Ubuntu please follow the instructions in the wiki.

Crashes

If an application crashes, Apport will start automatically, raising an appropriate bug report for you to complete in Launchpad. This provides developers with rich debugging information that will make it easier to fix the problem.

apport-1.png

Adding apport-collect information to an existing Launchpad bug

First, please do not run apport-collect more than once per release tested. For example, if you originally reported a bug about Precise via Apport, and then could reproduce it in Quantal, only run apport-collect once in Quantal. This minimizes unnecessary E-Mail traffic to those subscribed to your report and keeps the report efficient. If your problem is in the linux package, and you are not the original reporter, please do not apport-collect to a bug report unless specifically asked of you by a developer or triager. Running apport-collect when not asked creates spammy E-Mail traffic for those subscribed, clutters up the bug report with undesired attachments, and hinders the bug getting addressed quickly. As well, your attachments are subject to deletion at the discretion of developers and triagers. Instead, please open a new report via ubuntu-bug. Otherwise, if you have already reported a bug directly via Launchpad, but want to add additional debugging information via Apport to the bug report, you can do this by running the command:

apport-collect bug_number

via “Run Command” or terminal window.

Please note that attempting to run apport-collect bug_number against a linux package bug report, while booted into a mainline linux kernel will not work. This is due to how Ubuntu does not provide support for mainline kernels. For more on this, please see https://wiki.ubuntu.com/Kernel/MainlineBuilds#Kernel.2BAC8-FAQ.2BAC8-DebuggingMainlineBuildsSupport.Does_the_kernel_team_support_the_mainline_kernel_builds.3F.

Error: The launchpadlib Python module is not installed

If one gets the following error while trying to perform apport-collect:

ERROR: The launchpadlib Python module is not installed. This functionality
is not available.

please install the following package:

sudo apt-get -y install python-launchpadlib

Package libreoffice not installed and no hook available, ignoring

If one attempts to apport-collect and gets the error message:

Package libreoffice not installed and no hook available, ignoring

one has to install the following package:

sudo apt-get -y install libreoffice

Adding attachments to an existing Launchpad bug

Please ensure you do not use URL links to external posting sites (ex. pastebin.com, paste.ubuntu.com, dropbox.com, etc.) or post external hyperlinks for your attachments. Instead, if as per below you should add an attachment to a report, please post it directly to your bug report. As well, please do not compress attachments (.gz, .zip, etc.) or group mulitiple attachments together (.tar.gz). Attach one uncompressed file at a time.

Linux package bugs

If your problem is in the linux package, and you are not the original reporter, please do not add attachments, to a bug report unless specifically asked of you by a developer or triager. Adding undesired attachments when not asked creates spammy E-Mail traffic for those subscribed, clutters up the bug report with undesired attachments, and hinders the bug getting addressed quickly. As well, your attachments are subject to deletion at the discretion of developers and triagers. Instead, please open a new report via a terminal:

ubuntu-bug linux

Crash reports

If your attachment is a crash report (ex. found in directory /var/crash), please do not attach it to an existing report. Instead, file a new report via a terminal so that Apport Retracing Service may process it:

ubuntu-bug my_crash_report.crash

Non-crash userspace bugs

Sometimes it is useful to take a picture (with a camera or via PrtSc button), or screencast of the problem to demonstrate how you reproduced it, what the bug specifically shows, and the impact it has.

Filing a translation bug

You should file a translation bug if you are experiencing one of the following issues:

  • Wrong translations or spelling mistakes for languages other than English in applications
  • Errors in spellcheckers or language support
  • A string from an application not available for translation in Launchpad Translations

  • An application from the Ubuntu main repository not available for translation in Launchpad Translations

  • A translation made in Launchpad Translations and not updated in the Ubuntu language packs

  • A duplicate translation template (the same application can be translated in two different places) in Launchpad Translations

  • A template/translation no longer used in Ubuntu and that should be disabled from Launchpad Translations

In case of doubt, you can always contact the Translations team.

All translation issues should be filed against the Ubuntu Translations project. From there the bugs will be triaged and assigned to the right person and package.

Back to top

Getting advice

Still have doubts about the bug report filing process? You can ask someone on #ubuntu-bugs on the Freenode IRC server or on the bugsquad mailing list.

Back to top

Other languages

Back to top

See Also

ReportingBugs (last edited 2014-04-18 23:30:18 by keithzg)