Reporting
|
Size: 5277
Comment:
|
Size: 11129
Comment: Copyedit and refresh
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #title Reporting X Bugs ||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;">'''Contents'''[[BR]][[TableOfContents(2)]]|| |
#title Writing a Good X Bug <<Include(X/MenuBar)>> The official way to report defects against Ubuntu's Xorg is: {{{ ubuntu-bug xorg }}} This lets you attach a lot of common debugging data. But it's not enough!! Include a '''detailed description''' of the problem. * A '''good description''' * '''Step-by-step directions''' for how you reproduced it * When was your system '''last working''' properly? * '''photo''' of the screen If your report doesn't have a good description, and there's no relevant errors in your log files, your bug will be closed as not actionable and you'll be referred here. Don't be upset - the always-busy X package maintainers get a LOT of bug reports and need to focus their limited time on well-described problems. Instead, read this page and try again, making your new bug report a well-described problem. Keep in mind that the Launchpad bug tracker is a development tool, not for technical support - Ubuntu does have [[http://www.ubuntu.com/support|volunteer and paid technical support staff]] but none of them frequent the bug tracker. In particular, if you're using a released version of Ubuntu, you probably should start with the technical support channels. == Be Specific, Especially in the Title == X bugs often have very generic symptoms, like "booted with black screen", or "crashed", or "sluggish performance". Two people can have the same general symptom but completely different underlying bugs. Just like two people with "a headache" could have completely different illnesses. The problem is that other people will glom onto your bug report and sidetrack it to get their issue solved, and your issue will be ignored and your email box filled with a bunch of irrelevant emails. So be specific! == Focus on One Issue == The rule is "One Defect, One Person Per Report". You may find there are several problems with your computer, particularly after a big upgrade. But don't almalgamate every problem together; these may be distinct bugs, each needing analysis. Select one issue and report it. Feel free to mention the other problems in case they're relevant symptoms, but make it clear which problem you're aiming to get solved. Otherwise, the analyst will just pick one issue from your list that looks interesting to work on, and tell you to file bug reports on the other problems. == Avoid Saying 'Randomly' - Think Like a Scientist == Many times it's unclear what is causing the X problem. It's tempting to describe it as "just happening randomly". But the word "Randomly" just gives the impression you haven't given your problem much thought or study. If you don't care to think about it much, why would anyone else? So, avoid the word "randomly" (or "intermittently", "unexpectedly", et al.) Instead, think how you can characterize it. If it occurs every so often, guess how many minutes or hours on average it occurs? Does it happen only when you're doing stuff on the computer? Only when it's idle? Only after you've suspended and resumed? Treat writing your bug report like you would writing a chemistry lab report. Identify variables - what has changed recently about your system, what makes your system unique, what you're doing when the problem occurs. Take lots of measurements. Make a hypothesis and attempt to disprove it. Repeat the experiment and see if you get the same results. If you simply can't characterize it, consider holding off on filing a bug report until you have a better understanding and can describe it more specifically. == Be Prepared to Roll Up Your Sleeves == A bug report is not a support request, but a way to engage with the maintainers. This implies an expectation of your participation in the in the development process. It may be limited to just testing the fix and verifying it works, or it could be extensively technical. If that seems like more than you can handle, state so in the bug report so expectations are set properly, and so appropriate guidance can be given to you. Often, the more involved the reporter is at following up with new info, chasing down leads, and trying out variants, the more likely the bug will catch someone's interest and lend a hand. == Troubleshooting == Before reporting the defect you've found, take some time to analyze and isolate it: [[X/Troubleshooting]] A good defect report treats the issue scientifically, isolating when the problem happens and does not happen. Variables should be varied, such as configuration settings, driver versions, and so on. We provide snapshots of upstream versions of things in the xorg-edgers PPA; testing those to identify the issue is fixed or not fixed is invaluable. == Keep Calm and Carry On == Bugs can be frustrating, and X bugs particularly so. Your system may be completely broken and unusable. It may seem no one is giving any attention to the bug report, and you're feeling quite mad about the whole deal. But don't give in to the dark side. Losing your cool and ranting can be quite unproductive, and just makes you look bad for all posterity. Threatening to "Go back to windows", that the bug "drives away users", and so on does nothing to help spot a solution. Instead keep discussions civil, and follow the [[http://www.ubuntu.com/community/conduct|Ubuntu Code of Conduct]] and keep discussions civil, even if you're frustrated. There are millions of Ubuntu users, and thousands of bug reports and just a handful of people to work on fixes -- it simply is not humanly possible to give a personal reply to every bug report. If you're not getting fast enough response on a bug, then in addition to checking your analysis work and improving the defect report, you can try reporting it upstream, locate patches or workarounds to test and report your findings, or even try your hand at coding a fix yourself (if you know C coding). |
| Line 5: | Line 65: |
| = Bug Reporting = | == Reporting Bugs from a Different Machine == |
| Line 7: | Line 67: |
| The lifecycle of a bug report begins, unsurprisingly, with the preliminary report. How a bug is initially reported can have a huge effect on how it's handled and how quickly it gets fixed. |
Apport does a good job of collecting information on certain kinds of bugs. By default, it tries to launch your web browser to complete the bug filing. But sometimes you can't do this. Maybe X is utterly broken, or the buggy machine lacks a network connection, or some other problem. You can make apport capture bug data manually like this: {{{ apport-bug --save /tmp/foo.apport }}} Then copy that {{{foo.apport}}} file to the machine you want to file the bug from (using scp, rsync, a usb drive, or whatever), and then file it like this: {{{ apport-bug ~/foo.apport }}} |
| Line 12: | Line 82: |
| == Choosing a Good Title == | For the situation where apport automatically captured a crash dump from a crash or X lockup, but you can't file it from the sick machine, you will find the file in your {{{/var/crash}}} directory on the sick machine. Copy that over to another machine and file it from there, like above: |
| Line 14: | Line 84: |
| Your title should communicate two things: The symptom you're seeing, and whatever is unique or unusual about your system. Otherwise, your bug may not get proper attention. ''' Examples: ''' || '''BAD''':|| Crazy screen issues on boot || || '''BAD''':|| Multiple problems with CD today || || '''BAD''':|| Not able to login or start X after updating || || '''BAD''':|| Randomly doesn't work || || '''GOOD''':|| [Feisty] Screen briefly corrupts during boot with -nv (NVidia 6100) || || '''GOOD''':|| [Hardy Alpha-3] Alt-CD (only) selected wrong driver (Matrox / BenQ FP91+) || || '''GOOD''':|| [Gutsy] Periodic crashes w/ high CPU on Dell Latitude D505 (-intel 855GM) || || '''GOOD''':|| [Dapper,Edgy] Wrong default refresh rates on 16:10 LCD panels || || '''GOOD''':|| After update to -intel 2.0-0ubuntu3, X fails with 'Invalid mode' error || == Do's and Don't's == ||<tablestyle="width: 80%;" style="background-color: #FF8080;"> DON'T: || Assume "they must already know about this" || ||<style="background-color: lightgreen;"> DO: || Look for existing bug reports that match your problem || |||||| ||<style="background-color: #FF8080;"> DON'T: || Assume a "similar" bug is exactly what you're seeing || ||<style="background-color: lightgreen;"> DO: || File a new bug, but mention the ID's of all bugs that sound similar. Someone can dupe them together later. || |||||| ||<style="background-color: #FF8080;"> DON'T: || Add "me too" responses. Wastes everyone's time. || ||<style="background-color: lightgreen;"> DO: || Add missing data (photos, logs) to add to an existing bug's "knowledge base". Or if you just wish to be notified, then Subscribe yourself to the bug. || |||||| ||<style="background-color: #FF8080;"> DON'T: || Post bugs with only a brief description of the problem || ||<style="background-color: lightgreen;"> DO: || Post relevant logs, config files, and data (see table below) '''ALWAYS ATTACH YOUR /var/log/Xorg.0.log''' || |||||| ||<style="background-color: #FF8080;"> DON'T: || Assume "everyone" is seeing this same bug || ||<style="background-color: lightgreen;"> DO: || Consider what is unique about your system || |||||| ||<style="background-color: #FF8080;"> DON'T: || Assume others will "just know" how the bug occurs || ||<style="background-color: lightgreen;"> DO: || Itemize the exact steps that result in the issue. Can you reproduce it at will? || |||||| ||<style="background-color: #FF8080;"> DON'T: || Fire and forget. Abandoned bugs rarely get fixed. || ||<style="background-color: lightgreen;"> DO: || Follow up on your bug from time to time, even if it seems ignored. Report if the issue goes away or remains when new Ubuntu's come out. || |
{{{ apport-bug /path/to/file.crash }}} |
| Line 53: | Line 89: |
| == What to Include in Bug Reports == | The crash files can be unpacked (like if you only want certain files): |
| Line 55: | Line 91: |
| || '''Problem class:''' || '''Things to Include:''' || ||<|5(^> '''General X bug''' || Description of problem || || Paste in output of {{{lspci -nn | grep VGA}}} || || Attach /etc/X11/xorg.conf || || Attach /var/log/Xorg.0.log || || Attach output of `lspci -vvnn` || ||<|7(^> '''Wrong resolutions, refresh rates, or monitor specs''' || Resolution, rate, or other parameter expected || || Resolutions, rates, or other parameters actually obtained || || /etc/X11/xorg.conf || || /var/log/Xorg.0.log || || output of `lspci -vvnn` || || output of `sudo ddcprobe` || || output of `xrandr` || ||<|5(^> '''Wrong font dpi or size''' || Are you running GNOME, KDE, XFCE, or ...? || || Affected (and unaffected) applications || || /var/log/Xorg.0.log || || output of `sudo ddcprobe` || || Screenshot showing font differences || ||<|11(^> '''X crash, lockup, freeze, exit, or doesn't start/shutdown''' || Detailed description of problem || || List any versions you tried that did not have this issue || || Detailed list of steps to reproduce || || How complete is the X failure? [[BR]] + Does ctrl+alt+f1 take you to a console? [[BR]] + Does ctrl+alt+backspace restart X? [[BR]] + Does mouse pointer still move? [[BR]] + Does the keyboard LED come on when hitting the CAPSLOCK key? || || /etc/X11/xorg.conf || || /var/log/Xorg.0.log || || /var/log/Xorg.0.log.old || || ~/.xsession-errors || || output of `lspci -vvnn` || || output of `cat /proc/acpi/video/*/DOS` || || output of `sudo cat /proc/acpi/dsdt` || ||<|4(^> '''Keyboard, touchpad, and mouse issues''' || Description of the problem || || /var/log/Xorg.0.log || || output of `xprop -root` || || output of `gconftool-2 -R /desktop/gnome/peripherals` || ||<|4(^> '''Screen display corruption''' || Photo of the screen || || Description of the problem || || Does it also occur if DRI is disabled? || || /var/log/Xorg.0.log || ||<|3(^> '''Bad video playback''' || /etc/X11/xorg.conf || || /var/log/Xorg.0.log || || output of `lspci -vvnn` || |
{{{ mkdir ~/tmp apport-unpack /path/to/file.crash ~/tmp/ }}} == What Next? == Once your X bug is reported, it will be reviewed and triaged. The triager may mark it Incomplete and ask some questions or request additional information (if you're curious, or would like to participate in triaging, see [[X/Triaging]]). Due to the volume, automated scripts do the first level triaging to help sort out the high quality bug reports from the low. If there is no reply from you within a month or two, the bug report may be closed as out of date / invalid (otherwise the tracker fills up with inactive bugs and gets confusing). You should feel free to reopen it once you have the needed information. Once you've submitted your replies, a second round of triaging takes place to evaluate if the bug is a Duplicate of another defect report or not an issue requiring a fix at the distro level. If neither of those apply, the bug will be marked Triaged, which marks it ready for the next step. Once a report has made it to Triaged, the defect report may be assigned to a developer or forwarded to an upstream bug tracker. If it is forwarded upstream, you should also subscribe to that bug report so you can answer questions or run tests for the upstream developers. Once a fix is found either in Ubuntu or upstream, the Ubuntu developers will take the fix and package it for Ubuntu. They may ask for people to test and verify the fix before uploading it. == Frequently Answered Questions == Q. My bug got marked 'Confirmed', what does that mean? A. In Ubuntu-X the Confirmed state means the bug appears to have the necessary information for it to be reviewed by a developer. We employ scripts to move bugs to the Confirmed state when they have certain required files. The scripts don't check the description of the problem, so it's entirely possible for the script to mark a bug Confirmed that is later found to not be valid due to an ambiguous description or something. Q. There are a lot of bugs reported in Launchpad, does Ubuntu really plan to fix all of them? A. Ubuntu does not fix every bug. Actually most X.org bugs are fixed by upstream. Ubuntu's principle role is an 'integrator' which means we try to *get* the fixes and bring them to you. In some cases this involves fixing the issue ourselves, sometimes it means backporting a fix from upstream, and sometimes it means waiting until upstream has put out a new release of their code for us to incorporate. We don't have an omniscient view of every issue solved by every upstream change, so we don't always know exactly what fixed what (sometimes even upstream doesn't know.) This is why we sometimes just have to ask bug reporters to re-test with the newer versions and keep us informed. Q. I encountered a serious problem with the released version of Ubuntu and filed a bug report about it. Why hasn't anyone answered it? Don't you support your releases? A. The Launchpad bug tracker is mainly used by our development team to remove defects from the version of Ubuntu currently under development. Ubuntu also has both paid and volunteer technical support teams who focus on providing support for the releases, however they have separate tools for tracking support requests -- i.e., the support crew generally don't operate in the bug tracker. So, yes, releases are most definitely supported, but the bug tracker isn't the right place to ask for help. Q. What kinds of bug reports will get developer attention in the released version of Ubuntu? A. In general we try to avoid injecting a lot of random of changes into the released version of Ubuntu, since every change carries some risk of causing unexpected regressions. Each change needs to be carefully reviewed and thoroughly tested, and go through a stringent approval process. We only do this for defects that are well understood, with a clearly identified patch that is simple enough to see from the code whether it's unlikely to cause regressions. We generally only undertake the process once there has been a fix isolated and confirmed as fixing the problem. |
The official way to report defects against Ubuntu's Xorg is:
ubuntu-bug xorg
This lets you attach a lot of common debugging data. But it's not enough!!
Include a detailed description of the problem.
A good description
Step-by-step directions for how you reproduced it
When was your system last working properly?
photo of the screen
If your report doesn't have a good description, and there's no relevant errors in your log files, your bug will be closed as not actionable and you'll be referred here. Don't be upset - the always-busy X package maintainers get a LOT of bug reports and need to focus their limited time on well-described problems. Instead, read this page and try again, making your new bug report a well-described problem.
Keep in mind that the Launchpad bug tracker is a development tool, not for technical support - Ubuntu does have volunteer and paid technical support staff but none of them frequent the bug tracker. In particular, if you're using a released version of Ubuntu, you probably should start with the technical support channels.
Be Specific, Especially in the Title
X bugs often have very generic symptoms, like "booted with black screen", or "crashed", or "sluggish performance". Two people can have the same general symptom but completely different underlying bugs. Just like two people with "a headache" could have completely different illnesses.
The problem is that other people will glom onto your bug report and sidetrack it to get their issue solved, and your issue will be ignored and your email box filled with a bunch of irrelevant emails. So be specific!
Focus on One Issue
The rule is "One Defect, One Person Per Report". You may find there are several problems with your computer, particularly after a big upgrade. But don't almalgamate every problem together; these may be distinct bugs, each needing analysis. Select one issue and report it. Feel free to mention the other problems in case they're relevant symptoms, but make it clear which problem you're aiming to get solved.
Otherwise, the analyst will just pick one issue from your list that looks interesting to work on, and tell you to file bug reports on the other problems.
Avoid Saying 'Randomly' - Think Like a Scientist
Many times it's unclear what is causing the X problem. It's tempting to describe it as "just happening randomly". But the word "Randomly" just gives the impression you haven't given your problem much thought or study. If you don't care to think about it much, why would anyone else? So, avoid the word "randomly" (or "intermittently", "unexpectedly", et al.)
Instead, think how you can characterize it. If it occurs every so often, guess how many minutes or hours on average it occurs? Does it happen only when you're doing stuff on the computer? Only when it's idle? Only after you've suspended and resumed?
Treat writing your bug report like you would writing a chemistry lab report. Identify variables - what has changed recently about your system, what makes your system unique, what you're doing when the problem occurs. Take lots of measurements. Make a hypothesis and attempt to disprove it. Repeat the experiment and see if you get the same results.
If you simply can't characterize it, consider holding off on filing a bug report until you have a better understanding and can describe it more specifically.
Be Prepared to Roll Up Your Sleeves
A bug report is not a support request, but a way to engage with the maintainers. This implies an expectation of your participation in the in the development process. It may be limited to just testing the fix and verifying it works, or it could be extensively technical. If that seems like more than you can handle, state so in the bug report so expectations are set properly, and so appropriate guidance can be given to you.
Often, the more involved the reporter is at following up with new info, chasing down leads, and trying out variants, the more likely the bug will catch someone's interest and lend a hand.
Troubleshooting
Before reporting the defect you've found, take some time to analyze and isolate it:
A good defect report treats the issue scientifically, isolating when the problem happens and does not happen. Variables should be varied, such as configuration settings, driver versions, and so on. We provide snapshots of upstream versions of things in the xorg-edgers PPA; testing those to identify the issue is fixed or not fixed is invaluable.
Keep Calm and Carry On
Bugs can be frustrating, and X bugs particularly so. Your system may be completely broken and unusable. It may seem no one is giving any attention to the bug report, and you're feeling quite mad about the whole deal.
But don't give in to the dark side. Losing your cool and ranting can be quite unproductive, and just makes you look bad for all posterity. Threatening to "Go back to windows", that the bug "drives away users", and so on does nothing to help spot a solution. Instead keep discussions civil, and follow the Ubuntu Code of Conduct and keep discussions civil, even if you're frustrated. There are millions of Ubuntu users, and thousands of bug reports and just a handful of people to work on fixes -- it simply is not humanly possible to give a personal reply to every bug report. If you're not getting fast enough response on a bug, then in addition to checking your analysis work and improving the defect report, you can try reporting it upstream, locate patches or workarounds to test and report your findings, or even try your hand at coding a fix yourself (if you know C coding).
Reporting Bugs from a Different Machine
Apport does a good job of collecting information on certain kinds of bugs. By default, it tries to launch your web browser to complete the bug filing. But sometimes you can't do this. Maybe X is utterly broken, or the buggy machine lacks a network connection, or some other problem.
You can make apport capture bug data manually like this:
apport-bug --save /tmp/foo.apport
Then copy that foo.apport file to the machine you want to file the bug from (using scp, rsync, a usb drive, or whatever), and then file it like this:
apport-bug ~/foo.apport
For the situation where apport automatically captured a crash dump from a crash or X lockup, but you can't file it from the sick machine, you will find the file in your /var/crash directory on the sick machine. Copy that over to another machine and file it from there, like above:
apport-bug /path/to/file.crash
The crash files can be unpacked (like if you only want certain files):
mkdir ~/tmp apport-unpack /path/to/file.crash ~/tmp/
What Next?
Once your X bug is reported, it will be reviewed and triaged. The triager may mark it Incomplete and ask some questions or request additional information (if you're curious, or would like to participate in triaging, see X/Triaging). Due to the volume, automated scripts do the first level triaging to help sort out the high quality bug reports from the low.
If there is no reply from you within a month or two, the bug report may be closed as out of date / invalid (otherwise the tracker fills up with inactive bugs and gets confusing). You should feel free to reopen it once you have the needed information.
Once you've submitted your replies, a second round of triaging takes place to evaluate if the bug is a Duplicate of another defect report or not an issue requiring a fix at the distro level. If neither of those apply, the bug will be marked Triaged, which marks it ready for the next step.
Once a report has made it to Triaged, the defect report may be assigned to a developer or forwarded to an upstream bug tracker. If it is forwarded upstream, you should also subscribe to that bug report so you can answer questions or run tests for the upstream developers.
Once a fix is found either in Ubuntu or upstream, the Ubuntu developers will take the fix and package it for Ubuntu. They may ask for people to test and verify the fix before uploading it.
Frequently Answered Questions
Q. My bug got marked 'Confirmed', what does that mean?
A. In Ubuntu-X the Confirmed state means the bug appears to have the necessary information for it to be reviewed by a developer. We employ scripts to move bugs to the Confirmed state when they have certain required files. The scripts don't check the description of the problem, so it's entirely possible for the script to mark a bug Confirmed that is later found to not be valid due to an ambiguous description or something.
Q. There are a lot of bugs reported in Launchpad, does Ubuntu really plan to fix all of them?
A. Ubuntu does not fix every bug. Actually most X.org bugs are fixed by upstream. Ubuntu's principle role is an 'integrator' which means we try to *get* the fixes and bring them to you. In some cases this involves fixing the issue ourselves, sometimes it means backporting a fix from upstream, and sometimes it means waiting until upstream has put out a new release of their code for us to incorporate. We don't have an omniscient view of every issue solved by every upstream change, so we don't always know exactly what fixed what (sometimes even upstream doesn't know.) This is why we sometimes just have to ask bug reporters to re-test with the newer versions and keep us informed.
Q. I encountered a serious problem with the released version of Ubuntu and filed a bug report about it. Why hasn't anyone answered it? Don't you support your releases?
A. The Launchpad bug tracker is mainly used by our development team to remove defects from the version of Ubuntu currently under development. Ubuntu also has both paid and volunteer technical support teams who focus on providing support for the releases, however they have separate tools for tracking support requests -- i.e., the support crew generally don't operate in the bug tracker. So, yes, releases are most definitely supported, but the bug tracker isn't the right place to ask for help.
Q. What kinds of bug reports will get developer attention in the released version of Ubuntu?
A. In general we try to avoid injecting a lot of random of changes into the released version of Ubuntu, since every change carries some risk of causing unexpected regressions. Each change needs to be carefully reviewed and thoroughly tested, and go through a stringent approval process. We only do this for defects that are well understood, with a clearly identified patch that is simple enough to see from the code whether it's unlikely to cause regressions. We generally only undertake the process once there has been a fix isolated and confirmed as fixing the problem.
X/Reporting (last edited 2016-01-10 21:36:02 by penalvch)