Triaging Bugs

The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

This is a collection of guidelines for triaging Qt bugs.

Everyone is invited to join the efforts of triaging bugs, but it is expected that you know at least how to compile and run the examples that come with Qt.

Triaging bugs is a fun learning experience and a good starting point in contributing to Qt and making it the best possible product.

Jira

Qt uses Jira to manage bug reports, so the first step is to sign up there. The second step is to acquire triaging rights so that you can actually change the state of bugs. To do this, create a new issue for our JIRA itself, with the summary "Request for bug triaging rights for <your name>". Please name some persons who would support this request.

Searching

Once signed up, you can start searching for unevaluated bugs. There are existing filters that can be used for this, which can also be customised further by selecting additional criteria (such as a component that you have an interest in) or you can create your own search from scratch by either:

Pressing Enter in the quick search bar at the top right of the page, or
Clicking the "Issues" drop down at the top left of the page and then "Search for Issues"

The search criteria that is generally of interest when triaging is:

Project: Qt
Issue Type: Bug
Status: Open, In Progress, Reported
Priority: Not Evaluated

To see a list of filters, click the "Issues" drop down at the top of the page, and under the "Filters" section, click "more…".

Evaluating

Now that you have a list of bugs, you can start investigating individual cases. Before you do that, please keep in mind a few points:

Bug reports come from many different types of users, including students, hobbyists and managers of companies using Qt in their products. Not everyone who reports bugs is an experienced developer.
Not everyone reporting bugs is a native English speaker.
Bugs that affect Qt also affect the users of Qt and their products. Care must be taken to ensure that reported bugs are not closed without a proper attempt at reproducing them.

Please be respectful when communicating with reporters and other users interested in the resolution of a bug.

Below is a detailed walkthrough of how to approach triaging a specific bug.

What is the issue?

The most important part of triaging is to ensure that the issue being reported is understood. Don't invest any energy in attempting to reproduce a bug before you understand what the problem is. Don't be afraid to ask for clarification from the reporter if the bug report does not adequately describe the problem. A minimal, compilable example in the form of either an inline {code} snippet or an attached project is expected for anything but trivial issues. An issue without a compilable example should either be so simple as to not require one (for example, classwizard example crashes on startup) or be reproducable by following a set of simple steps.

Sometimes, the issue being described may be closer to a suggestion than a bug. This may be the case when the report acknowledges intentional behaviour but suggests that it is undesirable, or describes a feature that Qt should have, rather than an existing one that is broken. If this is the case, you can move the issue to a suggestion.

For more information on types of issues, see: https://confluence.atlassian.com/display/JIRA/What+is+an+Issue

Has the issue already been reported?

Use Jira's search feature to search for existing issues that this report might be a duplicate of. If your search doesn't yield useful results, try narrowing it by including fewer search terms. If the report indicates that the bug was recently introduced, sorting the search for existing bugs by the "Created" or "Updated" date can be useful.

If you deem a report to be a duplicate of another, you can close it as duplicate. Note that the report with the earliest "Created" date should be left open, as it is the original report. When you close an issue as a duplicate, you must link it to the original report that it is a duplicate of. To do this:

Click More Actions
Click Link
Under the This issue drop down, choose is duplicated by
In the Issue field, enter the bug number; for example: QTBUG-12345
In the Comment field, mention the reason for closing the bug; for example: "Duplicate of QTBUG-12345."

I think the issue is valid/invalid - what is the process for accepting/closing it?

If you have managed to reproduce the issue, you can accept it by clicking Accept. It is useful to leave a comment using the Comment field at the bottom of the Accept form, mentioning that you were able to reproduce it and the Qt version and environment that you reproduced it with. For example:

"Reproducible with Qt 5.1 on Windows 7 32-bit."

Include as much information as you think is necessary. If you had to create a compilable example to reproduce the issue, include the code as an inline {code} snippet in the Description field, or attach the project using the Choose Files button in the Attachment field. This will save others from rewriting the same code and will ensure that the steps to reproduce the issue are understood and agreed upon.

If there was already an example provided but you were unable to reproduce the issue with it, you can still leave a comment with an inline snippet or attach files using the Attach Files button found under the More Actions menu at the top of the page.

Is the priority correct?

The list of priorities and when to use them can be found by clicking on the ? (help) icon when editing a report, which links to this. A systematic approach is suggested in JIRA-Priorities . Even with this guide, assigning a priority can often be a subjective decision to make. To help make the process more objective, ask yourself:

Is the cause of this bug or the use case(s) it affects a common scenario or a corner case? A common scenario is documented and/or at least moderately simple to understand for those familiar with the area. A corner case is often obscure and/or does not follow the prescribed usage of a feature.
Is there a workaround?
How many users does this affect?

Are the affected components accurate? Is it assigned to the right person?

This can sometimes be difficult to determine. The important thing is to ensure that the report is assigned to someone, preferably a maintainer. Most components have a maintainer who will be assigned tasks for that component if you set the Assignee field to Automatic. Even if the assignee is incorrect, they can change the affected component(s) and assign it to the correct person.

Does the issue cover a large area of work?

Some issues might affect several pieces of code or imply modifications in several modules. This could require several people to work independently on different components. In such a case, creating sub tasks will allow better management of the work load and give a better overview of what needs to be done. Each sub task should identify an element that can be worked on, if possible independently from one another.

Someone attached a patch, what do I do with it?

For legal reasons, any non-trivial patches to Qt must go through Gerrit, as only there can the Qt Project be sure that the author of the patch has signed the Contributor License Agreement (CLA). The best course of action in this scenario is to leave a comment on the report thanking the author for their patch and politely request that they submit it through Gerrit, providing them with the link to the Contribution Guidelines that have detailed information on how to contribute code to Qt.

This report describes a security issue; what's the process for this?

If you suspect the issue is security-sensitive, forward it to the private security@qt-project.org mailing list. Do not comment on it publicly.

If somebody else (e.g., the reporter) has already mentioned the security impact, kindly remind them to follow the responsible disclosure process next time by mailing security@ directly. If the issue has non-trivial impact and is not widely known yet, notify a Qt Project administrator to have the issue visibility restricted.