Get Involved/Issue Reporting

From KDE Community Wiki
Revision as of 19:56, 18 September 2023 by Nclarius (talk | contribs) (fix spacing)
Help Konqi catch some bugs!

Have you found a problem with KDE Software, or a way that you think it could be improved? KDE would like to know about it! This page will give you an overview of the process of reporting a bug or making a feature request, teach you how to submit a good report, and walk you through the process of doing so using https://bugs.kde.org, KDE's Bugzilla issue tracker.

Issue reporting involves responsibility

Before you report a Bugzilla ticket, please make sure that you are:

  • ...using relatively recent versions of KDE software (≤ 1 year old) or an LTS supported version
  • ...willing to do whatever is necessary to get the bug to happen again (if reporting a bug)
  • ...willing to correspond with KDE developers about the issue, potentially over an extended period of time
  • ...prepared to gather and report a lot of additional information
  • ...ready to potentially use a terminal program to execute command line debugging tools

If those points all apply to you, then we can move on! Let's see now make sure that the issue you're experiencing is something that can be reported.

Step 0: Is it a security issue?

Do not file bug reports for security issues, as this makes the vulnerability public and could expose users to exploits. Instead, send an email to [email protected]. For more information, see https://kde.org/info/security/.

Step 1: Make sure it's a valid bug or feature request

Do not file Bugzilla tickets for vague or subjective matters, over-broad requests for giant changes to everything, support questions, or developer questions. Instead, you might try bringing up the matter on the KDE forum or another online discussion group of your choice.

Valid Bugzilla tickets describe crashes, broken functionality, anything that causes data loss, specific design or usability problems, translation problems, typos, and accessibility issues. Bug reports are also used for requesting new features (use the "wishlist" severity).

If any of the above describe your issue, proceed to step 2.

Step 2: Make sure it hasn't already been fixed

If you've found a real bug or want to request a new feature, 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 or implemented in a later release. 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.

If you are using one of these Linux distros, please try a newer version of the KDE software in question first, using one of the following methods:

Option A: try the nightly Flatpak build

Most KDE projects regularly build a "nightly" version of their latest code under development, which you can install. For applications on Linux, the easiest way to try reproducing with this "bleeding edge" code is to install the nightly Flatpak of the application, which you can run independently of updating your system's KDE packages. See Guidelines_and_HOWTOs/Flatpak.

If the problem is still present in the nightly build of the software, proceed to step 3.

Option B: upgrade your KDE packages

If the software in question does not have a nightly Flatpak build, or if the issue is in Plasma rather than a self-contained app, you can try to upgrade your system 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:
    sudo add-apt-repository ppa:kubuntu-ppa/backports && sudo apt update && sudo apt upgrade
  • Fedora:
    sudo dnf copr enable zawertun/kde && sudo dnf upgrade --refresh
  • 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 Bugzilla issues 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 (bugs only)

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 bug, 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. Please note that https://bugs.kde.org does not use the accounts defined on identity.kde.org right now.

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 then proceed with the usual 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 Bugzilla tickets that show up in the search results. If you find one that matches, great! Please do not intentionally open a duplicate Bugzilla ticket.

If you find an issue that's marked as RESOLVED FIXED that seems to describe your issue, do not re-open it or post a new comment in it. Issues that look alike often have subtly different root causes that need to be fixed separately. Instead, submit a new bug report and mention the one you found that's marked as already fixed.

If none of the Bugzilla tickets returned by the search seem to describe your issue, proceed to step 6.

Step 6: File a high-quality Bugzilla ticket

It's time to file a new Bugzilla ticket! 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 ticket should belong to, and don't worry if you get it wrong. This is what KDE's bug triagers are for! Over time you'll get a feel for which products correspond to which issues.

Summary

Every Bugzilla ticket 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.

Software versions

If your issue involves a KDE app, we need to know the app version; you can find that in the Program itself, in the Help menu > About <program> window.

If you are running KDE Plasma, Open the Info Center program, click the "Copy to Clipboard" button, and paste the output here.

Steps to Reproduce

Write a detailed Steps To Reproduce section in the Bugzilla ticket. Here is an example of a perfect Steps to Reproduce section:

Steps to Reproduce:
1. Open Discover
2. Click on Applications
3. Click on the search box, type an application name (Eg. VLC) and press enter
4. Click on the icon to enter the app description
5. Click on the cross to delete the text written in the search box
6. Click on the search box in order to write another word
7. Write another app name (Eg. Chromium)
8. Press ENTER to confirm the search
9. It always crashes

Screenshots and screen recordings

If the issue involves anything visible in the program's user interface, please include screenshots--or better yet, a screen recording. Bugzilla tickets that can show an issue visually have a much higher chance of being promptly resolved.

You can press the "Print Screen" button on your keyboard to open Spectacle to take a screenshot. To take a screen recording, we recommend the SimpleScreenRecorder app (on X11) or OBS (on Wayland). Screen recordings must use the webm format and be under 4MB in size.

Use the "Add Attachment" button to attach your screenshot or screen recording. Don't post links to images hosted elsewhere, as they will eventually go stale and the images will become inaccessible.

Things to avoid

Multiple issues in a single Bugzilla ticket

A Bugzilla ticket describing multiple issues is not actionable and is likely to be closed. Each Bugzilla ticket must describe only a single issue; file multiple Bugzilla tickets to report multiple issues. If the conversation in your Bugzilla ticket derails and starts to describe multiple issues, file other Bugzilla tickets to describe them, and try to redirect the conversation back to the original issue.

Proposing a solution

The problem you're encountering is obvious to you, but it will only be equally obvious to KDE's bug triagers and developers if you describe it with detail and accuracy. If you propose an initial solution without adequately describing the problem, they'll have a hard time helping you because they won't be able to figure out what's actually going on. Even if your proposed solution makes sense, it will be difficult to verify this without knowing what problem it would be solving. Always describe the problem itself, rather than proposing a solution to it.

Crash report without a backtrace

If you use the DrKonqi crash reporting assistant to report the bug, this will happen automatically. If not, or if the issue is a hang rather than a crash, you must include a backtrace yourself. Do not submit a Bugzilla ticket about a crash or a hang if you are unable to include a backtrace, as it is not actionable and will be closed.


Next steps

Thanks for the Bugzilla ticket! 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 Bugzilla ticket is not valued! Rather, it is a reflection of KDE's limited issue triaging resources. If you would like to help alleviate this situation, becoming a KDE bug triager is one of the absolute best ways to contribute!

Issue tracker etiquette

Using an issue 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 Bugzilla ticket is akin to mildly 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 patient. Think to yourself, "what would my mother say if she read my words here?"

More practically, acting rude, annoying, or argumentative is counterproductive because volunteer developers will avoid fixing issues that require them to interact with unpleasant people. Would you do unpaid work for a stranger who is annoying or insulting you? Probably not.

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

Most developers working on KDE software are unpaid volunteers. Those who are paid to work on KDE software are typically paid by their employer to work on specific areas of interest to their employer, not general user-reported issues.

As a result, there are extremely limited developer resources for fixing issues reported by users or even noticing and replying to them. Most of the time there will be a lot of waiting involved, and possibly a lot of discussion too. This is normal. If a Bugzilla ticket is going unaddressed, this is probably a sign that KDE's development resources are stretched thin. It is not helpful or effective to poke the developers by posting things like "Me too!" or "I have this bug as well!" or "Why doesn't anyone want to fix these very important issues? Doesn't KDE care?????" We definitely care, but we don't always have the resources to fix everything quickly!

Consider trying to fix the issue yourself, or donate money to KDE so that there are eventually enough resources to hire full-time developers to fix user-submitted bug issues.

Also, Bugzilla ticket are not assigned to specific people; anyone can fix a Bugzilla ticket, respond to the reporter, engage in discussion, and so on.

Have a thick skin

Sometimes your Bugzilla ticket will get closed without the resolution you're hoping for. This feels disappointing, but it's not the end of the world, so try not to take it personally. The project is larger than any one of us.

Submit patches using GitLab, not the issue tracker

A Bugzilla ticket with a patch is an incredible blessing. But patches attached to Bugzilla ticket tend to get missed and become stale over time, which is a real shame. Instead of attaching your patch to the Bugzilla ticket, please submit it as a merge request using GitLab instead, and paste a link to the merge request in the Bugzilla ticket.

Why don't you use GitLab issues?

See Why not GitLab Issues?.

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 Bugzilla ticket itself:

  • RESOLVED does not necessarily mean that the issue has been fixed for you, just that the Bugzilla ticket itself is no longer considered actionable by the developers.
  • RESOLVED FIXED means that the issue has been fixed by KDE, even if the version that contains the fix has not been relesaed yet, or if you are not yet using the version that contains this fix. This might be because have not yet upgraded your system, or because your distribution does not offer recent enough versions of KDE sofware, which is often the case with LTS releases. You can see which version of the KDE software is the oldest that the fix in the "Version Fixed In" field. If you find that your distribution dos not offer recent enough versions of KDE software for important bug fixes, you might want to consider switching to a different distribution that is closer to the release schedule of the software it ships.
  • RESOLVED WORKSFORME is used when the bug can no longer be reproduced by the original poster or any of the developers, even if it is not clear what fixed the issue for them.
  • RESOLVED DUPLICATE means that this particular bug report is no longer needed because the same issue is already tracked elsewhere, even if the issue in question has not yet been fixed.
  • "upstream" means 3rd-party software that KDE uses, for example the Qt library. So a bug will be marked as RESOLVED UPSTREAM if the issue is not in KDE itself but in some upstream software, even if the issue has not yet been fixed in that upstream library, or if the version of it that fixes the bug is not yet released or available in your distro. This is a normal outcome; KDE's issue tracker can only be used to track issues in KDE's own software.
  • "downstream" means 3rd-party software that uses KDE, for example your distribution. So a bug will be marked as RESOLVED DOWNSTREAM if the issue is not in KDE itself but somewhere downstream, even if that issue has not yet been fixed or even tracked by a bug report in the 3rd-party software's bug tracker.
  • RESOLVED INTENTIONAL 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 issue, cannot be fixed without an unreasonable amount of engineering effort, or it's a feature request that doesn't match the intended scope or design of the software.
  • RESOLVED NOT A BUG does not mean, "you're an idiot who doesn't know how to use issue trackers!" Rather, it means that the Bugzilla ticket itself is describing something that isn't a bug or feature request, or is something that KDE developers can't fix.
  • RESOLVED UNMAINTAINED does not mean that the bug is already fixed, but rather that it won't be fixed as the software it belongs to is no longer receiving updates, and so there is nothing else to act on in the report.