|
|
| (18 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| [[File:Mascot konqi-support-bughunt.png|thumbnail|right|Help [[Konqi]] catch some bugs!]]
| | #REDIRECT [[Get Involved/Issue Reporting]] |
| Have you found a problem with KDE Software? KDE would like to know about it! This page will give you an overview of the bug reporting process, teach you how to submit a good bug, and walk you through the process of doing so.
| |
| | |
| | |
| = Bug reporting involves responsibility =
| |
| First a word about the responsibilities of a bug reporter. When you go to report a bug, you are committing to...
| |
| * ...use relatively recent versions of KDE software (≤ 1 year old)
| |
| * ...do whatever is necessary to get the bug to happen again
| |
| * ...submit high-quality, actionable bug reports that describe real bugs
| |
| * ...correspond with KDE developers about the issue, potentially over an extended period of time
| |
| * ...potentially use a terminal program to execute command line debugging tools
| |
| | |
| Please only report a bug if you are willing to make these commitments. KDE's [[Guidelines and HOWTOs/Bug triaging | bug triaging resources]] are spread thin, and bug reports filed by people not willing to make these commitments are almost never actionable. Bug trackers that fill up with un-actionable bug reports become useless, and developers miss the ''real'' bugs.
| |
| | |
| If you are willing to commit, then great! Let's file a bug.
| |
| | |
| | |
| = Step 1: Make sure it's a real bug =
| |
| First, make sure that your problem is actually a bug. Real bugs involve crashes, data loss, features that don't work, user interface anomalies, and inconsistencies in behavior. Here are some examples of issues that are almost never real bugs:
| |
| * "The program is ugly"
| |
| * "The program should work more like this Windows program that I'm used to"
| |
| * "The program should use a different user interface style"
| |
| * "The program disappeared after I did a system update"
| |
| | |
| These types of issues are either subjective matters, design choices too broad to be changed by a bug report, features that you may be unfamiliar with, application-specific setting that can be changed, or caused by user or distro configuration choices. '''Do not file bug reports for these kinds of issues'''. Instead, You might try bringing up the matter on the [https://forum.kde.org/ KDE forum] or another online discussion group of your choice
| |
| | |
| Here are some examples of problems that are almost always real bugs:
| |
| * "The program crashed or hung"
| |
| * "The program caused unexpected data loss"
| |
| * "An advertised feature of this program simply doesn't work when I use it"
| |
| * "A button on the program's user interface is partially cut off"
| |
| * "A feature of the program that works fine most of the time stops working in Full-Screen mode"
| |
| | |
| For issues like these, always '''proceed onto step 2'''.
| |
| | |
| Here are examples of issues that ''may'' be real bugs, but require some more investigation:
| |
| * "The program is really slow"
| |
| * "Some of the program's icons are inconsistent"
| |
| * "The program did something unexpected in response to an action that I took"
| |
| * "The label for one of the program's user interface controls doesn't clearly indicate what it does"
| |
| | |
| For issues like these, '''proceed to Step 2''', but be prepared for the issue to be caused by configuration or hardware issues, or simply be an example of unfamiliar behavior.
| |
| | |
| | |
| = Step 2: Make sure it hasn't already been fixed =
| |
| If you've found a real bug, you're well on your way! But wait... are you using the latest version of the program? If not, it may have already been fixed in a later release. For example, if you are experiencing an issue with Dolphin 16.04, but the current version of Dolphin is 17.12, then you're missing out on almost two years worth of bugfixes! Many Linux distros--including popular ones like Linux Mint, Debian Stable, Kubuntu, and openSUSE Leap--will intentionally hold back newer versions in the name of stability. But this won't help you if you're encountering a bug!
| |
| | |
| You should first upgrade your packages. Here's how to do it for various distros.
| |
| {{Warning|Due to the nature of package dependencies, this will upgrade the entire KDE software stack. Do not proceed unless you are okay with this.}}
| |
| * Kubuntu: <pre>sudo add-apt-repository ppa:kubuntu-ppa/backports && sudo apt update && sudo apt upgrade</pre>
| |
| * Fedora: [insert openSUSE Leap instructions here; delete list item if it isn't possible]
| |
| * openSUSE Leap: [insert openSUSE Leap instructions here; delete list item if it isn't possible]
| |
| | |
| If you are unable to upgrade your packages, '''please don't file bugs against a version of KDE Software that's more than a year old'''. Many of these bug reports will be closed as already fixed, and this takes up our faithful bug triagers' valuable time!
| |
| | |
| If the problem is still present in a recent version of the software, '''proceed to step 3'''.
| |
| | |
| = Step 3: Make sure you can reproduce it =
| |
| So your issue is a real bug, and it's still present in a recent version of the software. But if it only happened once and you cannot get it to happen again no matter what you do, then there is almost no chance that it can be fixed. '''Please do not report bugs that you cannot reproduce'''.
| |
| | |
| If you can reproduce the issue, '''proceed to step 4'''.
| |
| | |
| | |
| = Step 4: Log into or set up a Bugzilla account =
| |
| Navigate to https://bugs.kde.org/. If you already have an account, click the "Log in" text and enter your username and password, then '''proceed to Step 5'''.
| |
| | |
| If this is your first time on the KDE Bugzilla, it's time to sign up for an account! Click on the "New Account" text at the top of the page. You will be prompted for your email address and can go through the normal process of setting up an account. Log into your new account and '''proceed to step 5'''.
| |
| | |
| = Step 5: Make sure it hasn't already been filed =
| |
| First, let's make sure that this issue hasn't already been reported. Navigate to https://bugs.kde.org/query.cgi and search for a few keywords that describe your problem. For example, if the problem is that Dolphin crashes when you attempt to access a samba share, you might search for "dolphin samba crash".
| |
| | |
| Look through the bugs that show up in the search results. If you find one that matches, great! '''Please do not file a duplicate'''.
| |
| | |
| If none of the bugs seems to describe your issue, '''proceed to step 6'''.
| |
| | |
| | |
| = Step 6: File a high-quality bug report =
| |
| It's time to file a new bug report! Click on the "New" text in the top-left corner of the screen. You will be presented with a list of products. Take your best guess for what product the bug report should belong to, and don't worry if you get it wrong. This is what KDE's bug screeners are for! Over time you'll get a feel for which products correspond to which issues.
| |
| | |
| === One issue per bug report ===
| |
| '''Only report a single issue per bug report.''' A bug report describing multiple issues is not actionable and is likely to be closed. Each bug report '''must''' describe only a single issue; file multiple bug report to report multiple issues. If the conversation in your bug report derails and starts to describe multiple issues. File other bugs to describe them, and try to redirect the conversation back to the original issue.
| |
| | |
| === Crash reports must include backtraces ===
| |
| '''A bug report describing a crash must include a backtrace.''' If you use the DrKonqi crash reporting assistant to report the bug, this will happen automatically. If not, [[Guidelines and HOWTOs/Debugging/How to create useful crash reports|you must include a backtrace yourself]]. Do not submit a bug about a crash if you are unable to include a backtrace, as it is not actionable and will be closed.
| |
| | |
| <br/> <br/>
| |
| In your bug report, include the following information:
| |
| === Summary ===
| |
| Every bug needs a good title, which goes in the "Summary" field. A good title succinctly describes the issue, can be read as a complete sentence, and avoids using charged language. Examples of good titles:
| |
| * "Discover 5.12 crashes when I navigate to an app page and search twice"
| |
| * "Gwenview's "Exit Full Screen" button becomes inaccessible with the sidebar is opened"
| |
| * "KIO Local copy performance with 50,000 small files in Dolphin is 4.5x slower than using `cp`"
| |
| | |
| And here are the kinds of titles that you should avoid:
| |
| * "App always crashes"
| |
| * "HELP HELP HELP CANNOT ACCESS MY FILES ANYMORE THX"
| |
| * "Old version worked much better; new version is terrible"
| |
| * "Cannot do anything"
| |
| * "bug"
| |
| | |
| === Software versions ===
| |
| First, find out what versions of various pieces of KDE software you're running. Open the Info Center program (which is installed in all KDE Plasma environments) and write the following in the top of the bug report:
| |
| <blockquote>
| |
| Distro and version (e.g Kubuntu 17.10)<br />
| |
| Qt version (e.g. Qt 5.9.1) <br />
| |
| KDE Plasma version (e.g. Plasma 5.12)<br />
| |
| KDE Frameworks version (e.g. Frameworks 5.42)<br />
| |
| </blockquote>
| |
| | |
| If your issue involves a KDE app, we need to know the app version, too. You can find that in the Program itself, in the Help menu > About <program> window
| |
| | |
| === Steps to Reproduce ===
| |
| Write a detailed ''Steps To Reproduce'' section in the bug report. Here is an example of a perfect Steps to Reproduce section:
| |
| <blockquote>
| |
| '''Steps to Reproduce:'''<br />
| |
| 1. Open Discover<br />
| |
| 2. Click on Applications<br />
| |
| 3. Click on the search box, type an application name (Eg. vlc) and press enter<br />
| |
| 4. Click on the icon to enter the app description<br />
| |
| 5. Click on the cross to delete the text written in the search box<br />
| |
| 6. Click on the search box in order to write another word<br />
| |
| 7. Write another app name (Eg. chromium)<br />
| |
| 8. Press ENTER to confirm the search<br />
| |
| 9. It always crashes<br />
| |
| </blockquote>
| |
| | |
| === Screenshots and screen recordings ===
| |
| If the bug involves anything visible in the program's user interface, it is '''highly''' recommended to include screenshots--or better yet, a screen recording. Bugzilla tickets that can show the issue visually have a much higher chance of being promptly resolved.
| |
| | |
| You can use Spectacle to take a screenshot. By default, it will open in response to the "Print Screen" button on your keyboard. To take a screen recording, we recommend the SimpleScreenRecorder app. Screen recordings must use the webm format and be under 4MB in size.
| |
| | |
| You can use the "Add Attachment" button to attach a screenshot or screen recording.
| |
| | |
| === Additional information ===
| |
| If there is any additional information or attachments that you feel would help KDE developers reproduce, investigate, or fix the issue, please mention it here!
| |
| | |
| | |
| = Next steps =
| |
| Thanks for the bug report! You just helped make KDE software a little bit better.
| |
| | |
| Monitor the email address that you use for your Bugzilla account. You will receive an email if a KDE bug triager or developer needs to contact you for any reason.
| |
| | |
| Nevertheless, since KDE is a mostly volunteer project, you may not receive an immediate response. This is normal and should not be taken to mean that your bug report is not valued! Rather, it is a reflection of KDE's limited bug triaging resources. If you would like to help alleviate this situation, [[Guidelines and HOWTOs/Bug triaging | becoming a KDE bug triager]] is one of the absolute best ways to contribute!
| |
| | |
| = Bug tracker etiquette =
| |
| Using a bug tracker may be an unfamiliar experience. Here are some tips to help your interpersonal interactions be as smooth as possible:
| |
| | |
| === Remember your manners ===
| |
| Filing a bug is akin to criticizing someone's work--work that was likely done for free, on personal time, as a labor of love. Please respect the developers by being polite, and not using rudeness or insults; think to yourself, "what would my mother say if she read this?" In addition to being bad manners, it's counterproductive because you will provoke defensiveness and spark arguments, and developers will not feel like doing the work that you're requesting. Would ''you'' do unpaid work for a stranger who you felt had insulted you?
| |
| | |
| === Avoid arguments ===
| |
| Arguing almost always gets nowhere, and both parties simply become more entrenched in their existing opinions. If you feel resistance building, take a few hours or a day to cool down, and then try another approach later.
| |
| | |
| === Have realistic expectations ===
| |
| Sometimes, KDE developers will have the bug fixed in under 24 hours, which is amazing. But most of the time, there will be a lot of waiting involved. This is normal. If the bug is going unanswered, this is probably a sign that KDE's development resources are stretched thin, so you might consider trying to [[Get Involved/development|fix it yourself]]!
| |
| | |
| === Have a thick skin ===
| |
| Sometimes your bug report will get closed without the resolution you're hoping for. This feels disappointing, but it's not personal. The project is larger than any one of us.
| |
| | |
| === Don't confirm your own bug ===
| |
| Do not set your own bug to the CONFIRMED status. This status exists for KDE bug triagers and developers.
| |
| | |
| === Submit patches using Phabricator, not the bug tracker ===
| |
| A bug report with a patch is an incredible blessing. But patches attached to bug reports tend to get missed and become stale over time, which is a real shame. Instead of attaching your patch to the bug report, please submit it using [[Infrastructure/Phabricator|Phabricator]] instead, and paste a link to your Phabricator revision in the bug report.
| |
| | |
| === Understand what the resolution statuses mean ===
| |
| Some of them can sound a little harsh, but again, don't take it personally. These words are just descriptions of the different statuses for the bug report itself:
| |
| * RESOLVED does not necessarily mean that the bug has been fixed for ''you'', just that the bug report itself is no longer actionable by the developers. For example, a bug report may be marked as RESOLVED UPSTREAM if it's traced to a Qt issue, even if the Qt issue has not yet been fixed, or the version of Qt that fixes the bug is not yet available. This is a normal outcome on bug trackers; if you want to issue fixed for yourself faster, comment in the upstream bug report, or ask your distro to backport the fix for you.
| |
| * RESOLVED WONTFIX does '''not''' mean "shut up and go away, we don't care!" What is much more likely is that the issue is not actually considered a real bug, or cannot be fixed with a reasonable amount of engineering effort.
| |
| * RESOLVED INVALID does '''not''' mean, "you're an idiot who doesn't know how to use bug trackers!" Rather, it means that the bug report itself is describing something that isn't a bug or that KDE developers can't fix.
| |
