Reporting Bugs

English ಕನ್ನಡ

[toc align_right="yes" depth="3"]

Reporting bugs in Qt

Bugs in Qt can be reported at the "bug tracker":http://bugreports.qt.io/. The quality of the bug report can dramatically impact how likely it is that the bug will be fixed. A prerequisite for this is that a number of people (for example developers, code reviewers, QA and release managers) are able to quickly understand and verify the issue by reading the report and potentially running a code example. This page describes how to report bugs, and tips for making high quality reports.

Step by step

Here is a nutshell description of how to report a bug:

1. Visit "bugreports.qt.io":http://bugreports.qt.io/
2. If it's your first time, create an account (which is separate from your DevNet account). Make sure to supply a valid email address; Qt developers sometimes need to ask for more details regarding a bug, and this is the only way they can reach you. Your email address will not be exposed; it is only possible to contact you by commenting on your reports (or commenting on bugs you're watching).
3. Use the “Quick Search” field in the top right to try to find any similar bugs. If you find one, then…
   • Leave a comment with any additional info you have.
   • Click "Vote" — You will usually have a higher chance of having your bug fixed by voting on an already existing bug than creating a new one.
   • Add yourself as a watcher, if you want to track the progress of the bug via email.
4. If you don't find a bug report which matches your issue, then click “Create New Issues”, and fill out the fields.

Summary

• Enter a short but descriptive text explaining the bug in a sentence.
• This should include an overall overview over how the bug happens without going into too much detail. They key is to think about what other people might search for.
  • Bad example: "QLineEdit always goes wrong"
  • Too long: "QLineEdit crashes in paintEvent at the for loop which draws characters. This happens if I use an input method based on XIM and then set it to Arabic, which also switches to right-to-left mode. Then I try to type something, and it crashes." A long text like this one should be put in the description instead; the summary should be kept short.
  • Good example: "QLineEdit crashes in paintEvent when using an input method in right-to-left mode."
  • If you are sure the bug affects only one platform, prefix it by the platform and a colon: "Windows: QLineEdit crashes in paintEvent when using an input method in right-to-left mode."
  • If the bug is a regression, that is, it worked in a previous version of Qt, indicate this as follows: "[REG 4.8.6->5.3.1] Windows: QLineEdit crashes in paintEvent when using an input method in right-to-left mode."

Affects Version

• Select the Qt version where you're able to reproduce the bug. If this is not the current minor version, please also verify against the current minor version to check whether the bug has been fixed in the meantime.

Components

• Select the component which best fits the location of the bug.
• You can select more than one component by selecting one after the other from the drop-down menu. For example, if a widget problem is specific to Windows, you should select “Platform: Windows” and “Widgets”.

Description

• A longer text describing, step by step, the minimum amount of actions required to reproduce the bug.
• A good form to follow is this:
  1. What did you do? This ideally takes the form of short bullet points. However, try to be as precise as possible when describing something like a touch gesture.
  2. What did you expect to happen?
  3. What happened instead?
• If the bug is a crash, a vital piece of information in crash reports is the stacktrace. Retrieving a stracktrace is platform specific, however, all of them require that Qt be built with debug symbols. If you compiled Qt yourself, then make sure you supplied “-debug” during configure time. If you're using binaries, then make sure you’ve installed the corresponding debug packages. Paste the stacktrace in the description if it’s not terribly long (surround it by

  {noformat}My stack trace{noformat}
  

  to make it stand out from the rest), else attach it as a text file (use the suffix .txt so that it can be conveniently viewed by clicking). In Qt Creator, a verbose stack trace can be created by right-clicking on the stack window of the debugger and choosing Create full backtrace .
• Finally, please supply any more details that you may have in this field. For instance “This bug only occurs if I have compositing enabled”, or “This is a regression from 4.6.1”.
• Example:
  • Launch attached example qtbug32777.zip
  • Click on File Menu
  • Choose item "Open"
  • Note: Mouse cursor turns green
  • EXPECTED: File dialog opens
  • ACTUAL: Application crashes

Environment

• Input as detailed description of your operating system, window manager, compiler, and any other pertinent information needed to reproduce the bug.
• Also put the exact name of the package you used as well as the contents of the .tag file in the package if there is one. If using Git, please give the branch name and the commit ID.
• If you tested several platforms, it helps to add this information as well ("Windows: reproduced, Linux/KDE: not reproduced, OS X: reproduced"). As mentioned above, if you are sure the bug affects only one platform, it should be mentioned in the summary.
• Starting from version 5.3.0, there is a command line tool qtdiag, which outputs detailed information about operating system, compiler and graphics configuration. Particularly for bugs related to graphics, it is recommended to redirect its output into a file and attach that to the bug report, or add the output as a comment enclosed in {noformat} tags.

Attachment

• This often neglected field is perhaps one of the most important. Here is where you can make a simple application that reproduces the bug and attach it.
• Ideally, that should be an archive consisting of a main.cpp and a .pro file that expands a directory whose name indicates the bug number and optionally some identifier (for example, qtbug32765_printbug.zip expanding a directory qtbug32765_printbug). The stand-alone main.cpp file should have the bare minimum amount of code needed to reproduce the bug. An application that reproduces the bug is the single most useful piece of information for a developer to try to identify and fix a bug. Qt Creator's Other Project / Code Snippet wizard is a useful tool to create such examples. Remember that the application (referred to as the test case) should follow the SSCCE rule:
  • Short – Make it as short as possible. It is much easier to spot a problem in short code.
  • Self Contained – Make sure you do not rely on any external libraries or files other than Qt. If you need extra nonstandard headers, copy paste what you need (but not more than you need) into the main.cpp file. If you need moc, you can put #include "main.moc" at the end of the file to force moc to include the metacode directly into your file.
  • Correct – Make sure your application compiles and is correct code. For example, dereferencing a zero-pointer in the example code, is clearly not a bug in Qt.
  • Example – Make sure that the application actually demonstrates the problem you are trying to solve.
  • Avoid Qt Designer forms
  • The example should output the version of Qt it uses (set QT_VERSION_STR as window title or output it via qDebug()).
  • Particularly if it is a regression, the example should compile with Qt 4 and Qt 5.
  • Avoid the use of #ifdef to show workarounds. Use simple command line options instead:

if (QCoreApplications::arguments().contains("-w")) …

• A unit test (of the kind you can find in the $QTDIR/tests/auto folder in the Git repository) is even better than a simple example, since we can add it to our automated tests to make sure this bug doesn't regress later.
• A screenshot, or longer stacktrace is also incredibly useful.

Source Req ID

• Leave blank

Followed By

• Not needed

Then click “Create"

You can now either start hacking on Qt to find a solution and file a merge request, or wait until a Troll prioritizes, schedules, and fixes the bug for a release.

In short

Always provide as much information as possible together with your bug report. The more the better. Also, please specify if a bug is a regression or not. If it is, then specify what version it worked in last. Finally, supplying a testcase main.cpp is a sure-fire way to land in the “fasttrack” of bug resolution and into the hearts of the Trolls. Also, providing a testcase is a great means of preventing the same bug from cropping up in the future as a regression.

By creating a high quality bug report, you will gain priority over those less descriptive, and your chances of a speedy resolution increased. If after all your hard work we still reject your bug, then please don’t take it personally. Instead, add a comment in the report and explain your situation so that we can re-evaluate it. After all, we also make mistakes.

Bugs with security-sensitive information

If you found a security problem, do not create a bug report on JIRA, but send email to security@qt-project(dot)org.

Reporting bugs as a commercial customer

qt.io is a community resource, and may not always provide the experience you expect as a paying customer. If the problem you want to report has a high priority for you, you should use the "Digia customer portal":http://qt.digia.com/Log-in-Customer-Portal/ to report it. The support team can help you with many of the steps detailed on this page, suggest workarounds, and will create a JIRA task on your behalf and tag it appropriately.

Tips for dealing with difficult bugs

Some bugs may be hard to reproduce, for example, it may happen only occasionally, it cannot be reproduced in a small example, or it only happens in a specific environment. However, for the Qt developers to be able to help you, it is still important that they are analyzed in enough detail so that the developer is able to see the problem for himself. This section describes some tips for dealing with such bugs.

Bugs that occur in a specific environment

This type of bug often follows this pattern:

1. You identify a bug on your computer.
2. You manage to create a test case for it and submit that to "http://bugreports.qt.io/.":http://bugreports.qt.io/
3. A developer from Qt tries the example, but claims that he can not reproduce it.
4. He/she may also close the bug with “Cannot reproduce” or “Need more info”.

At this point, it important not to lose hope. These bugs are tricky, and solving them typically requires a lot of back and forth communication, since the bug can only be reproduced on the reporter’s system.

You should start by asking for pointers in the comment field. A typical question would be: “Where would be a good place in the code to start debugging or place some debug print statements?” Most developers should respond favorably to this, and suggest places to look at in detail, or specific variables that you can check for consistency while the code runs. This, in turn, may lead to additional questions being asked, which hopefully leads to either the bug being identified, or the Qt developer being able to reproduce the problem on his machine using the new information.

Bugs that cannot be reproduced in a small example

Typical for this type of bug is that in your big application, the bug can be easily triggered by enabling a certain attribute, for example

widget->setAttribute(Qt::WA_NativeWindow)

However, when you try to reproduce the same thing in a small example, the bug cannot be seen anymore.

One effective way of dealing with such bugs is the divide-and-conquer method. This method consists of a series of steps, where at each step, you remove a part of your program. Each time you remove something, you need to verify that the bug can still be reproduced, and if it can’t you have to go back to the previous step and choose a different part to remove.

Start by removing code that is likely to be irrelevant to be bug, for example if the bug is a rendering bug, you should quite safely be able to remove networking code. Similarly, if your program has 20 QPushButtons, but only one is required to demonstrate the problem, remove the other 19.

Eventually, your program may reach a point where you are not able to remove any more code without the bug disappearing. Such a program is an excellent candidate for a test case that you can submit to the bug report. This whole process can take quite some time, but is sometimes the only way of isolating the real cause of a bug.

Bugs that only happen occasionally

These are usually the hardest types of bugs. The key here is to be prepared when the bug does happen. This can mean several things, for example, if the bug is a crash, make sure that you are always running in a debugger so that you can look at the stack when the crash happens. If there is a behavioral bug, for example a visual problem or corrupt data, try to put debug prints in various key locations, printing the value of variables that may be relevant to the problem, and make sure you always log those values. Then, when the problem happens, you can see at which point the variables started to go wrong.

Like the bugs that only happen in a certain environment, this is something that you can ask about in the bug comment field and most developers should give you some hints about which places and variables may be important to your type of problem. The Qt mailing lists are also a good place to ask, as well as the #qt-labs channel on the Freenode IRC network. (For a full list of IRC channels of interest to Qt developers, see OnlineCommunities.)

Things that used to work (regressions)

If you have a bug in Qt that is difficult to produce a test case for, but you know that the feature worked in the past, bisecting can be of a great help to pinpoint the problem. Bisection is a process in the Git version control tool that allows you to iteratively search for the exact commit that broke a given feature. A full description of the git-bisect process will not be given here, but this will give you an idea of the process involved:

1. git bisect start
   

2. git bisect good v4.6.2
   

   (Mark the previous version you know about where the feature worked)

3. git bisect bad
   

   (Mark the current commit as broken)
4. Git should produce something like: Bisecting: 675 revisions left to test after this (roughly 7 steps)
5. Compile Qt as well as your application, and test if the bug is present.

6. git bisect <good|bad>
   

   (Good or bad depending on the outcome of the bug test)
7. Repeat the previuos two steps.
8. Eventually, git-bisect will tell you which commit introduced the problem. Include this commit in your bug report.

For more information on bisecting, please see the "git-bisect man page.":http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html

Feature requests (named Suggestions in JIRA)

Feature requests are a bit different from bugs. They often (but not always) have a wider scope than bugs. For example, “Port Qt to platform X” is a feature request that sounds simple, but has a huge scope.

The important thing to remember when submitting feature requests, particularly those with a big scope, is to be specific in the description:

• Bad example: Please add QWidget::nudgeWidget().
• Good example: Please add a function to QWidget that will make the window shake for a short period of time, like when the user enters a bad password. The function can be called something like nudgeWidget().

In the second example, it is much clearer to the developer what the feature request actually means, since the meaning of “nudge” is ambiguous (it could also mean blink the colors of the window, like some advertisement popups do when browsing the Internet).

Another very important piece of information in feature requests is to attach use cases. Use cases are concrete examples on situations where the feature will be used. For instance, the widget shaking in response to a bad password in the example above, is one such use case.

Even though the use case may be crystal clear to the reporter, it may not be to the developer, so it is better to be explicit about it. If you have several distinct use cases, feel free to list more than one. That makes it more obvious that the feature can be useful for many people.