Guidelines and HOWTOs/Bug triaging: Difference between revisions
Beefed up the section about triaging specific products' bugs |
m re |
||
| Line 175: | Line 175: | ||
= Useful Links = | = Useful Links = | ||
* [https://bugs.kde.org/page.cgi?id=fields.html A Bug's Life Cycle] | * [https://bugs.kde.org/page.cgi?id=fields.html A Bug's Life Cycle] | ||
* [[Guidelines and HOWTOs/Debugging/How to create useful crash reports]] | * [[Guidelines and HOWTOs/Debugging/How to create useful crash reports]] | ||
* [http://aseigo.blogspot.com/2009/01/bugskdeorg.html aseigo's suggestions for bugs.kde.org] | * [http://aseigo.blogspot.com/2009/01/bugskdeorg.html aseigo's suggestions for bugs.kde.org] | ||
Revision as of 16:37, 10 April 2018
KDE bug triagers verify that Bugzilla tickets describe real bugs, are accurate and reproducible, and that the reporter has given enough information. The goal is to save developers from doing this work, which helps them fix bugs more quickly and do more work on KDE software.
You don't need any programming knowledge to be a bug triager, but experience has shown that members of this team often learn a lot in the course of dealing with bug reports, and many move on to developing the software itself. If you are just starting to learn programming, it's a great way to gain familiarity with the components and give practical support to the KDE community.
General considerations
- Be polite. Bug triagers are the face of KDE. Be nice to bug reporters, even if they aren't nice to you! You have an opportunity to showcase the best of the KDE community, and turn skeptics into fans. Being nice is often more impatcful than being right. If you need to request information or feedback, be clear and polite and you will get more information in less time.
- If you are not familiar with the Bugzilla (KDE bug tracker system) interface, you may find this guide useful: Quick Introduction to Bugzilla
Decide what to work on
Today's bug reports
- All the bugs (any type) reported today or the last week
- All the crashes reported today or the last week
- All the normal bugs reported today or the last week
- All the feature requests reported today or the last week
All bug reports of a single product
You'll want to use the Advanced search for this: https://bugs.kde.org/query.cgi
You can see which products are most in need of bug triaging here, with links to their bug lists: https://bugs.kde.org/weekly-bug-summary.cgi?tops=50&days=7
Here are some common and popular KDE products in need of bug triaging:
- Plasma bugs / feature requests
- System Settings bugs / feature requests
- Dolphin bugs / feature requests
- Okular bugs / feature requests
- Gwenview bugs / feature requests
- Konsole bugs / feature requests
- Kate & KTextEditor framework bugs / feature requests
- KIO framework bugs / feature requests
What to do with bug reports
Now that you have a list of bug reports, pick one and start working! Here is the optimal bug triaging workflow:
There are several things that must be checked and "fixed" to make an initial bug report an interesting and useful piece of information for the developers.
Note
Identify duplicates
As KDE has so many users, we get a lot of reports about bugs which have already been reported (duplicates). Before putting any effort in the current report, check for an existing report. If you find a pre-existing bug report describing the same issue, mark this one as a duplicate of it.
Please see the article on identifying duplicates.
Identify bugs caused by external issues (UPSTREAM/DOWNSTREAM)
If you imagine software as a river, then software KDE uses that comes from others (e.g. Qt, X11, the Linux kernel) is UPSTREAM of KDE, and others who make use of KDE software (e.g Linux distributions, 3rd party Plasma plugins) are DOWNSTREAM of KDE.
Not all real bugs affecting KDE software are caused by a fault in KDE software.
Examples of upstream issues:
- KDE app crashes in QtQuick
- KDE app experiences an issue, but only when using the proprietary NVIDIA driver
Examples of downstream issues:
- A KDE app crashes because a dependent package is not automatically installed in distro X, Y, or Z
- Fonts are really hard to read, but only in distro X, Y, or Z
- Graphical corruption with a Plasma theme downloaded from store.kde.org
Ask for any missing information
Now that you know that the bug report is unique and that it is not an external issue, you need to check that all the needed information is there.
- If the description is not written in English and you cannot understand it, you may want to ask other KDE contributors to translate it for you. Alternatively, you can ask the reporter to use some online translation system (you won't get a clear explanation, but it is something).
- If the reporter has not indicated what versions of KDE Plasma, Qt, and KDE Frameworks they are using, and this information seems necessary to triage the bug report, ask them to provide that information and remind them about https://community.kde.org/Get_Involved/Bug_Reporting#Software_versions
- If the explanation is not clear enough, ask for clarification and concrete Steps to Reproduce, and remind them about https://community.kde.org/Get_Involved/Bug_Reporting#Steps_to_Reproduce
- If the issue is hard to picture without a visual aid and there are no screenshots attached, ask for one--or better yet, a screen recording--and remind them about https://community.kde.org/Get_Involved/Bug_Reporting#Screenshots_and_screen_recordings
- If the bug report is about a crash and the backtrace information is not really complete (and you couldn't perform a duplicate search), ask the user to install the missing debug symbols package, reproduce the bug, and generate a new backtrace. Point them to Guidelines and HOWTOs/Debugging/How to create useful crash reports
Note
Reproduce the bug
At this point, the bug report enough is complete enough that you should use the information provided by the reporter and try to make the bug appear on your own system.
Note
Warning
You may want to use this reference text to setup your testing environment: Preparing a testing environment
If you can't reproduce with any scenario mentioned in the comments, you may want to try other related situations. Hopefully you will find a combination that reproduces the bug reliably. Write down any newly discovered steps to reproduce.
If you cannot reproduce the bug under any circumstances
Write down the steps you performed. You may want to ask the reporter if your steps missed something, or if anyone notices any other strange or non-default situation or configuration which may be related.
Hopefully, you will get feedback from the reporters and you could gather more information to try to reproduce the bug or close the report as RESOLVED WORKSFORME (or FIXED). Time to move onto the next bug!
If you can reproduce the bug
If you had to combine several steps to make your own "recipe" to reproduce, write them down. This kind of information is useful for the developers. If you had to use custom input data (text, or a file), you may want to attach it to the bug report. And mention the environment and circumstances under which you can reproduce the bug.
Reassign the bug report to a different Product, if necessary
Many bug reports are reported against the wrong product. This may happen because the original reporter didn't know which application/library the bug belongs to. For example, many bugs filed to Dolphin are actually about KIO (the I/O framework) or Baloo (the search frameworks). Remember to check the KDE related technologies list
Warning
Set Bugzilla fields
Often a bug report isn't properly categorized, or lacks some information in the Bugzilla fields (which are useful for sorting and filtering). If a field isn't mentioned below, you don't need to change it. All users have permission to change most Bugzilla fields.
Version
If the report has an application version, you need to set the version in the Bugzilla field. Ideally the version field should reflect the latest version the bug is reproducible with. If the version is missing in the list, please contact the software maintainer or the KDE Bugzilla admins to add the version.
Severity
Mark the bug's severity. Some hints about the various severity options:
- Critical: A widespread, easily reproducible issue that causes data loss
- Grave: The software is basically unusable, with no workaround
- Major: A major feature is broken, and the workaround (if any) is painful and difficult
- Crash: The software crashes or hangs
- Normal: It's a bug that should be fixed, possibly with a reasonable workaround.
- Minor: Minor cosmetic issue or loss of function with an easy workaround.
- Wishlist: Request for a new feature or enhancement.
Platform
This field is only important if the bug is related to one distribution or a specific system (most of the bug reports are common to most of the platforms).
Keywords
If the bug seems like it would be really easy to fix, add the "junior-jobs" keyword. Examples of issues that would be easy to fix:
- Inaccurate description or text label
- Visual layout inconsistencies
- Pixellated icons when an app is run in HiDPI mode
- User interface element is the wrong color when using Breeze Dark
New code contributors often start with "junior-jobs"" bugs, so ensuring that there is a steady supply of bugs tagged with this keyword helps them get started with small, manageable tasks.
If the bug involves a poor user interface or demands a tedious workflow, tag it with the "usability" keyword, and it will be considered a part of KDE's "Usability & productivity" initiative.
Status
If you can reproduce the issue, and you are confident that its Product is set correctly, set the bug report's status to CONFIRMED. This only applies to bugs; feature requests ("wishlist" items) don't need to be confirmed, since they're not bugs.
Rename the bug report, if necessary
The bug report's summary might not accurately represent the bug, especially after you have triaged the bug and found the root cause or determined it to be another issue. You may want to update the summary to contain enough information to identify the issue properly. A good summary:
- Is readable as a grammatically correct English sentence
- Contains a brief explanation of the root cause (if it was found)
- Includes some of the symptoms people are experiencing
- Includes ClassName::FunctionName pairs if the bug describes a crash
- Isn't too long
Special circumstances
Bug describes multiple issues
You must close the bug report as RESOLVED INVALID with a humane explanation that bug reports can only contain a single issue. Reming the reporter about https://community.kde.org/Get_Involved/Bug_Reporting#One_issue_per_bug_report
Bug includes a patch
If the bug reporter or someone else included a patch, ask them to submit it using Phabricator, and remind them about https://community.kde.org/Get_Involved/Bug_Reporting#Submit_patches_using_Phabricator.2C_not_the_bug_tracker
Reporter seems very technically knowledgeable
Sometimes a very technically knowledgeable bug reporter will correctly identify the source of the issue, and maybe even the exact line of code that's causing the problem. Encourage them to submit a patch, and point them to https://community.kde.org/Get_Involved/development
Same person reports a lot of bugs
Anybody who reports a lot of KDE bugs--especially if they are high quality bugs--is quite likely a committed KDE user who is a good candidate for becoming a more involved contributor over time. Stumbling on someone like this in the bug tracker is like striking gold. Take every opportunity to develop a relationship with this person and try to guide them through the KDE "get involved" pipeline. Oftentimes people who submit a lot of bugs move on to bug triaging and then later development.