Guidelines and HOWTOs/Bug triaging - KDE Community Wiki

Guidelines and HOWTOs/Bug triaging - KDE Community Wiki
Jump to content
From KDE Community Wiki
Guidelines and HOWTOs
Help
Konqi
catch some bugs!
KDE's bug triagers go through new and old
open
bug reports to move them forward, with the end goal of making them actionable for developers. We verify that a bug exists, has not already been reported, whether it is reproducible, and that the reporter has provided enough information.
Our goal is to save developers from this task, which helps them fix bugs more quickly and do more work on KDE software.
One of the great things about bug triaging is that
you don't need any programming knowledge
, only basic familiarity with KDE software and a rough overview of how the Linux software stack is arranged (e.g. Plasma on top, Qt below it, various middleware libraries below Qt, and the kernel at the bottom).
That said, experience has shown that members of this team learn a lot about KDE and Qt programming during the course of dealing with bug reports, and many move on to developing the software itself. If you're just starting to learn programming, bug triaging is a great way to gain familiarity with the technical details of KDE's software architecture and provide practical support to the KDE community.
When you start triaging, an existing member can help you out as a mentor. Also, our community of triagers are happy to answer questions. Just stop by the
KDE Bugs Matrix group
and introduce yourself!
Getting started
General considerations
Be polite.
Bug triagers are the face of KDE to reporters. They have taken time out of their day to write up a report we can use to help our software improve. 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 more impactful than being right.
Focus on open reports.
Generally, this means a status of REPORTED or REOPENED. The
quick Introduction to Bugzilla
has details on the different statuses you need to be familiar with.
Be thoughtful and explain your decisions.
It can be very frustrating for a bug reporter if their report is suddenly closed without any reason given, or with no action taken. Especially when you close a bug report, write why you think your action is the correct one, and don't establish your opinion as the all-ruling fact. Some canned responses and explanations that have been shown to work well can be found at
Don't be afraid to make mistakes.
Everybody makes mistakes, especially when starting out with bug triaging.
Taking action is valuable even if it doesn't make a report actionable - yet.
Incremental progress in a bug report is still progress. Feel free to do what you can to move a bug forward. Feel free to leave a report open if you can't reproduce but someone else might, or someone might have more experience to move the bug further.
Get to know Bugzilla.
KDE uses the Bugzilla bug tracker system. If you are not familiar with it, you may find this
quick Introduction to Bugzilla
useful.
Bugzilla setup
Bugzilla is more comfortable to use for bug triaging purposes with a few changes to its default settings.
See details here
System Setup
It's very important to be using the latest versions of KDE software. In general, only the latest version is supported, and it's common for people to report bugs against old versions, so you need to be able to identify this situation.
It's highly recommended to use a rolling release or semi-rolling distro, such as Arch or an Arch derivative, KDE Neon, Fedora KDE, Solus, or openSUSE Tumbleweed. Ideally you'll be daily-driving such a distro, but if not, using it in a VM for bug triage purposes is better than nothing.
Slow discrete release distros like Ubuntu, Debian, and openSUSE Leap are not recommended.
Having VMs with different distros installed can be very useful for getting details about bugs with particular setups. This is not necessary, but a useful option.
Decide what to work on
All bugs filed recently
Going through all open bugs submitted recently in an organized manner is hugely impactful. Here are some links to Bugzilla searches that will update automatically over time:
All bugs and feature requests reported
today
or in the
last week
All Plasma bugs and feature requests reported
today
or in the
last week
All bugs reported
today
or in the
last week
All feature requests reported
today
or in the
last week
All crashes reported
today
or in the
last week
All bug reports of a single product
You'll want to use the Advanced search for this:
You can see which products are most in need of bug triaging here, with links to their bug lists:
Note
It's recommended to introduce yourself to the maintainers of a project before starting to triage its bugs, and to get familiar with their process. The best way is to join the appropriate room on
Matrix
If you're unsure what the right room is, just ask in the
KDE Bugs Matrix group.
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
Kdenlive
bugs
feature requests
Gwenview
bugs
feature requests
Konsole
bugs
feature requests
Kate & KTextEditor framework
bugs
feature requests
KIO framework
bugs
feature requests
Bug editing permissions
All regular Bugzilla users can perform standard edits to change fields such as the product, component, version, platform, status, and more. However only users with elevated permissions can do bulk editing, change the Importance fields (Priority and Severity), and re-open CLOSED bugs. After getting comfortable with the KDE Bugzilla process--or if you are the maintainer of a KDE product--you can request those permissions via a
Sysadmin ticket
Triaging bugs
The goal of bug triaging is to ensure that every report in the bug tracker is actionable for a developer to start working on. All of your actions should work towards this goal. For most bugs, your task is to clean them up so that they can be found and actioned by a developer. For bugs that
cannot
be made actionable, they need to be closed.
Note
If at any point you aren't sure how to proceed, move onto the next bug, or ask for help from a KDE developer or another more experienced contributor.
Close bug reports that aren't actionable
There are many reasons why a bug report might not be actionable:
It's not a bug
It's common for people to mis-perceive intentional design decisions or features they aren't familiar with as bugs. Some users have the presence of mind to check first on a forum or Reddit or somewhere else, but others jump straight into the bug tracker. In this case, close the bug report as RESOLVED/INTENTIONAL and gently explain to the user that the design or feature is intentional, and that in the future, they might benefit from first asking a question at
It was reported against an old and unmaintained version of the software
It's also common for people to report bugs against a version of the software that is no longer eligible for maintenance from KDE. The Bug Janitor will catch some of these in Plasma, but it won't get them all, and doesn't run at all for bugs on apps and frameworks. In these cases you'll need to handle the situation yourself.
First, determine if the software version was maintained when the bug was submitted. Generally, you can use the
release schedules
to get an idea of how long ago something was released. When you're new to triaging, please ask in the
KDE Bugs Matrix group
about whether something is still maintained
If you're sure the software is no longer maintained, close the bug report as RESOLVED/UNMAINTAINED and gently explain that KDE's resources are so limited that we can't offer support for older, non-LTS versions of the software. A canned response for Plasma
be found here
Warning
if you're triaging old bugs,
everything
will be reported against an old version, so instead try this canned response:
It's a duplicate of an existing bug report
As KDE has so many users, we get a lot of reports about bugs which have already been reported but not yet fixed. Identifying these is mostly a matter of experience, but if the bug being reported is reproducible and extremely obvious, it's quite likely it's already been reported somewhere, so mark it as a duplicate of the existing bug report. See
the article on identifying duplicates
for specific instructions on how to find duplicate issues.
It's a bug, but it was already fixed
It's common for people to report bugs that have already been fixed in an upcoming version of the software. If there's an existing bug report for it, mark it as a duplicate of that one. If not, close it as RESOLVED/FIXED and fill in the "version fixed in" field with the upcoming version that will have the fix in it. This is where having a system with the version with the bug, and a version with the fix is handy, since you can prove the problem has been fixed.
It's a bug, but not a KDE bug (i.e. UPSTREAM/DOWNSTREAM issues)
KDE software sits on top of a very tall software stack. Many layers of this stack will provide functionality that KDE apps use, but don't provide themselves. As a result, not all real bugs affecting KDE software are actually caused by issues in KDE software! The issue may be "upstream" or "downstream" of KDE.
"Upstream" means that the problem lies in an underlying technology that KDE software uses (e.g. Qt, X11, the Linux kernel, a GPU driver). Others who make use of KDE software (e.g Linux distributions, 3rd party apps or Plasma plugins) are
downstream
of KDE.
Examples of Upstream issues
A KDE app experiences a new behavioral issue after upgrading to a newer version of Qt.
A KDE app crashes in QtQuick.
A KDE app experiences an issue, but only when using the proprietary NVIDIA driver.
The bluetooth widget doesn't allow connection to a device, but neither does bluetoothctl.
Weird graphical glitches that turn out to be caused by a graphics driver problem.
If a bug is deemed to be caused by upstream software, it's ideal if it's tracked by a bug report in the affected project. If one exists, put it in the URL field of the KDE bug report and then close it as RESOLVED/UPSTREAM. Of no such upstream bug report exists or can be found, you can encourage the reporter to submit one themselves (and then put it in the URL field of the KDE bug report) if they seem very technically knowledgeable. Otherwise, submit one yourself on behalf of the bug reporter.
Examples of Downstream issues
A KDE app crashes because a dependent package is not automatically installed by the user's distro.
Fonts are really hard to read, but only in certain distros.
Graphical corruption with a Plasma theme downloaded from store.kde.org.
If a bug is caused by downstream software, it's acceptable to close it as RESOLVED/DOWNSTREAM and let the bug reporter report it there themselves.
It's a feature request that would be impractical to implement, or goes against the project's vision
In general we try to be lenient with feature requests, but sometimes people offer up ideas that would:
Be impossible to implement
Consume so many development resources as to be impractical
Go against the project's intended vision and user experience
For example, adding a video player widget to a document viewer, or changing default settings to values that don't match what the target user group would need
Amount to requests to re-engineer the entire world
In these cases, gently explain that feature requests need to be narrowly-tailored and implementable, and close the bug as RESOLVED/INTENTIONAL. Relevant canned response:
"Feature request for a giant un-actionable design change"
If the reporter seems technically competent and ambitious, you might consider encouraging them to work on it themselves.
Polish up any bug reports that are or might be actionable
At this point, the bug report might be a real actionable issue that can be fixed by a KDE developer. Great! Let's help it stand out from the rest and be easily findable and actionable.
Move it to the right place
There are many products on KDE's Bugzilla, so it's common for a bug report to be submitted to the wrong one. We even encourage people to report bugs to the generic "kde" product if they don't know what to do. This is fine; just move it to the right place.
Where bug reports should live is something that mostly needs to be learned over time, but you can check the
KDE related technologies list
for a start. Sometimes errors are obvious, such as when a bug report is about an app but it's reported against the "plasmashell" product.
Warning
Only reassign the bug report if you're sure it's in the wrong product.
Fix obvious metadata field errors
Quickly go through the bug report's metadata; fields like Version First Reported In, platform, severity (the second combobox on the 'importance' row"), and so on, and correct them. For example:
If the user listed the platform or version fields in a way that doesn't match the information in the body of the bug report, set the fields to match the text.
If the user reported a feature but didn't use the "wishlist" severity, change it to wishlist.
If the user reported a feature, but phrased it as a bug report (e.g. "Error: app can't do [thing that it currently doesn't do]"), rephrase the title and change the severity to wishlist.
Note
The "version first reported in" field is for reporting the
first
version that the bug has been reproduced against, not the latest version.
If the correct version or platform is missing from the list, contact the software maintainer or the KDE Bugzilla admins to get this corrected.
If it's a reasonable wishlist (aka feature request)
In general we try to be lenient with feature requests, so if the requested feature seems at all reasonable and feasible to implement to you, and if it seems aligned with the maintainers' intended user experience, then mark it as CONFIRMED. Add a note to the effect that the maintainers will consider the request for implementation.
Ask for any missing information
Now it's time to fill in missing info.
Every time you ask a bug reporter for information, put the bug report in NEEDSINFO/WAITINGFORINFO status. This does two things:
Hides the bug report from lists of open bugs
Closes the bug report automatically if there's no response after a month
Things that commonly need asking about:
If the explanation is not clear enough for you to easily understand what the problem is and how you can test it, ask for clarification and concrete steps to reproduce. (
Get Involved/Bug Reporting#Steps to Reproduce
If the issue is hard to picture without a visual aid and there are no screenshots or a screen recording attached, ask for one. (
Get Involved/Bug Reporting#Screenshots and screen recordings
If the bug report is about a crash and they did not attach a backtrace, or the backtrace information is incomplete or lacking debug symbols, ask the user to install the missing debug symbols packages, reproduce the bug, and generate a new backtrace. When you do this, set the status to NEEDSINFO/BACKTRACE. Relevant canned responses:
"no backtrace"
and
backtrace missing debug symbols
If the reporter has not entered the platform (i.e. it's "unspecified/Linux") and they didn't indicate which platform/distro they're using in the text, ask them.
If the reporter has not indicated what versions of KDE Plasma, Qt, and KDE Frameworks they are using, ask them to provide that information, and also set the version field accordingly.
Reproduce the bug
At this point, the bug report is complete enough that you should use the information provided by the reporter and try to make the bug appear on your own system.
If you cannot reproduce the bug under any circumstances
Write this down, and mention the software version and distro you tested on. Ideally also write down the steps you performed.
Consider asking the reporter if your testing missed something, or if anyone notices any other strange or non-default situation or configuration which may be related. Hopefully, they'll provide feedback that can help you reproduce the issue. If you still can't reproduce the issue under any circumstances, leave the bug in REPORTED state and move onto the next one. Hopefully someone else can reproduce it, or a developer with more technical knowledge can help.
If you can reproduce the bug
Set the bug's status to CONFIRMED and write that you can reproduce the bug on your system, mentioning the version if it's newer than what the bug reporter is using. If the way you reproduced the bug differs from how the reporter reported it, write that down too.
It's also acceptable to mark a bug report as CONFIRMED if it has multiple duplicates even if you cannot personally reproduce the issue; clearly it is something real if multiple people are experiencing it the same issue.
Set the Severity field
Mark the bug's severity (the second combobox on the 'importance' row) according to these definitions:
Severity
When to use it
Critical
A widespread, easily reproducible issue
that causes personal data to be destroyed or leaked publicly
Grave
The software becomes basically unusable, with no known workaround
Major
Like Normal, but with no known workaround, or the workaround is painful and difficult
Crash
The software crashes or hangs
Normal
Something isn't working the way it was designed to work, with a known workaround that isn't too painful
Minor
A cosmetic issue, awkward UX, or weird interaction between non-default yet supported components
Wishlist
An idea for how the product could become better in the future by doing something it currently doesn't do
Task
A technical maintenance chore like porting to a new API or refactoring some code to reduce future bugginess
Set relevant Keywords
Set whichever keywords from this table are relevant (the full list and definitions can be found
[1]
Keyword
When to apply it
regression
Something that worked in the past, but is now broken
Problems with keyboard navigation, screen reading tools, or other assistive technologies
efficiency-and-performance
Something related to power efficiency, performance, optimization, CPU spikes, etc.
usability
Something that involves a poor user interface or demands a tedious workflow
Issues related to the privacy of users' personal information, files, and other data
rtl
Bugs regarding right-to-left languages
junior-jobs
A bug that seems like it would be really easy to fix. Examples include inaccurate text, visual layout inconsistencies, and user interface elements using the wrong color with Breeze Dark
wayland-only
A bug that only manifests on Wayland (not on X11)
X11-only
A bug that only manifests on X11 (not on Wayland)
qt6
A bug that only manifests on software built with Qt 6
qt-crash
A crash whose backtrace is entirely in Qt
multiscreen
Bugs related to a multiscreen workspace
needs_verification
A bug that needs a specific piece of hardware or environment to reproduce. An example would be a bug that may need an NVIDIA GPU to reproduce
Rename it if needed
The bug report's summary might not accurately represent the bug, especially after you've 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
Common yet tricky bugs
There are a few persistent categories of bug reports that can have multiple underlying root causes and require specialized knowledge and handling. See theme at
Guidelines_and_HOWTOs/Bug_triaging/Tricky_bugs
Bug report describes multiple issues
You may, at your discretion, use the report to focus on the first or most important issue reported, and ask the reporter to open other reports for the remaining issues. Otherwise, close the bug report as RESOLVED/NOT A BUG with a
humane
explanation that bug reports can only contain a single issue. (
Get_Involved/Issue_Reporting#Multiple_issues_in_a_single_Bugzilla_ticket
). Sample text can be found at
Bug report includes a patch
If the bug reporter or someone else included a patch, ask them to submit it using GitLab, and remind them about
Get_Involved/Issue_Reporting#Submit_patches_using_GitLab.2C_not_the_issue_tracker
Bug 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
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.
Bug Janitor
KDE bug reports are overseen by a basic
bug janitor bot
that does the following things:
Nudges bugs in NEEDSINFO status after 15 days with no response
Closes bug reports in NEEDSINFO status as RESOLVED/WORKSFORME after 30 days with no response
Automatically sets the severity to "crash" if the title matches any of various keywords (e.g. "crash", and "coredump")
Automatically sets the severity to "wishlist" if the title matches any of various keywords (e.g. "feature request", and "wish")
Increases the priority to HI when a bug report has 5 duplicates
Increases the priority to VHI when a bug report has 10 duplicates
Closes Plasma bugs with a gentle message that were reported against a version that's not the latest maintained version
Retrieved from "