Reporting
|
Size: 12385
Comment:
|
Size: 11129
Comment: Copyedit and refresh
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| ||<tablestyle="float:right; font-size: 0.9em; background:#F1F1ED;margin: 0 0 1em 1em;" style="padding:2.0em;"><<TableOfContents(2)>>|| We welcome reports of defects in Ubuntu that help us make Ubuntu a better product. |
#title Writing a Good X Bug <<Include(X/MenuBar)>> |
| Line 11: | Line 10: |
| The {{{ubuntu-bug}}} script will automatically include a lot of files and information we need for troubleshooting problems. Also be sure to include: | This lets you attach a lot of common debugging data. But it's not enough!! |
| Line 13: | Line 12: |
| * A '''detailed description''' of the defect you found. * Steps or conditions to reproduce or a measurement of the frequency of how often it occurs * If it is a regression, make sure to indicate the '''last working version''' * A '''photo''' of the screen (if it involves graphical corruption or weirdness) * For crashes: [[http://wiki.ubuntu.com/X/Backtracing|A full backtrace]] |
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 |
| Line 19: | Line 18: |
| Take time to analyze the problem and write a good report, and '''especially include a detailed description of the problem''', including steps to reproduce it. Defect reports which do not define the issue needing to be fixed are likely to be closed as ambiguous. | 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. |
| Line 23: | Line 22: |
| Please be aware that a LOT of people file bug reports to Ubuntu, way more than we can respond to. We try to focus on the highest quality defect reports, so spending some time making a good report can help a lot. | == Be Specific, Especially in the Title == |
| Line 25: | Line 24: |
| 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. |
|
| Line 34: | Line 58: |
| == Choosing a Good Title == | == Keep Calm and Carry On == |
| Line 36: | Line 60: |
| Your title should communicate two things: The symptom being seen, and whatever is unique or unusual about the system in question. | 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. |
| Line 38: | Line 62: |
| ''' Examples: ''' ||<style="background-color: lightgreen;"> '''GOOD''':|| Screen briefly corrupts during boot with -nv (NVidia 6100) || ||<style="background-color: lightgreen;"> '''GOOD''':|| [fglrx] atieventsd crashed with SIGSEGV in XextAddDisplay() || ||<style="background-color: lightgreen;"> '''GOOD''':|| [Hardy Alpha-3] Alt-CD (only) selected wrong driver (Matrox / BenQ FP91+) || ||<style="background-color: lightgreen;"> '''GOOD''':|| [Gutsy] Periodic crashes w/ high CPU on Dell Latitude D505 (-intel 855GM) || ||<style="background-color: lightgreen;"> '''GOOD''':|| [Dapper,Edgy] Wrong default refresh rates on 16:10 LCD panels || ||<style="background-color: lightgreen;"> '''GOOD''':|| After update to -intel 2.0-0ubuntu3, X fails with 'Invalid mode' error || ||<style="background-color: #FF8080;"> '''BAD''':|| Crashes randomly || ||<style="background-color: #FF8080;"> '''BAD''':|| Crazy screen issues on boot || ||<style="background-color: #FF8080;"> '''BAD''':|| Multiple problems with CD today || ||<style="background-color: #FF8080;"> '''BAD''':|| Not able to login or start X after updating || == One Defect, One Person Per Report == In your defect report, '''focus on one specific issue'''. It is not uncommon to have several different unrelated bugs, but it makes it hard to track the issue to closure with them all in one report. Similarly, often several people will see the same symptom, but X failures tend to have very similar symptoms even though the underlying bugs are unrelated. So we will focus on only the original reporter's issue. '''Don't report 'me too' on someone else's defect report'''. == Do's and Don't's == ||<tablestyle="width: 80%;" style="background-color: #FF8080;"> DON'T: || Use the word "randomly" to describe the problem || ||<style="background-color: lightgreen;"> DO: || Describe the defect in a scientific manner. "randomly" indicates you've not studied the bug long enough to define it properly.|| |||||| ||<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 easily dupe them together later. || |||||| ||<style="background-color: #FF8080;"> DON'T: || Add "me too" responses to an existing defect report, with no further information. || ||<style="background-color: lightgreen;"> DO: || If you must comment on someone else's report that you're seeing the problem as well, at least include evidence (in the form of logs, photos, etc.) that you have the same problem. Explain in enough detail that you add value to the discussion, not just spam everyone with a contentless 'me too'. || |||||| ||<style="background-color: #FF8080;"> DON'T: || Post bugs with only a brief description of the problem, or none at all || ||<style="background-color: lightgreen;"> DO: || Post steps to reproduce, relevant logs, config files, and data (see table below) '''For Xorg issues, 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: || 99% of the time you are seeing something abnormal that others aren't. Consider what is unique about your system, any recent changes made, and so on. || |||||| ||<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. || |||||| ||<style="background-color: #FF8080;"> DON'T: || Rant about the bug "driving away new users", threaten to "go back to windows" unless the bug is fixed, or complain the bug is not getting enough attention. None of this helps get the bug fixed; it just makes people sad. || ||<style="background-color: lightgreen;"> DO: || 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). || |
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 108: | Line 88: |
The crash files can be unpacked (like if you only want certain files): {{{ mkdir ~/tmp apport-unpack /path/to/file.crash ~/tmp/ }}} |
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)