Reporting Bugs

Suggest edit

One of the big advantages of being an openly developed project is being able to take part in public bug tracking. However, if you’re new to working with public bug tracking, it can be difficult to understand how to report bugs The Right Way™. So let’s find out how:

  • We utilize the public issue tracker, GitHub Issues Tracker, to keep track of current and resolved issues.
  • When filing a new report, it’s a good idea to search the issue list to make sure your report hasn’t been filed already. If your report has already been filed by someone else, you should add the reaction to the report to indicate that you are also affected. Only comment on the report if you can provide additional useful information that may help track down the source of the issue. Do not comment things like, “I have this problem too” or “This is a really important issue”.
  • If your report has not already been filed by someone else and you’ve reached the “New Issue” page, type in a summary and description of the issue and select “Submit new issue”. Keep in mind the following information while filing your report:

Be Specific In The Summary

This will be the title of the issue in the bug tracker. It’s very important to be specific because it makes it much easier for a developer or bug manager to search the issue list and helps avoid duplicate reports. A summary such as “App Not Working” is not good and vague requests like “Increase Performance” are not helpful. A good summary is something like “Notification is not sent when process finishes”.

Avoid Subjective or Ambiguous Adjectives

This may sound like a repeat of the first heading, but it’s important when you want someone to confirm your report. Don’t say that something is “jarring” or “unintuitive”. Instead describe what happened and contrast it with what you expected to happen. “The Toast suddenly appeared instead of being animated in, ” describes the problem in a way that is actionable and objective.

Be Concise, But Explain The Issue

First of all, it’s important to mention that bug reports should be written in English and you should, if possible, watch out for your language and grammar.

The most important thing for a report is that the developer must be able to reproduce the issue. If necessary, include exact numbered steps to reproduce the issue.

Also remember that error reports are created in the hope that other users with the same problems will be able to participate in solving them together with you. But do not expect others to quit and start fixing your problem. The bug report is designed to help you and others start working together to resolve a problem.

Be Prepared To Provide More Information

If your report does not contain enough information for the developer to reproduce the issue, it may be marked as “Incomplete”. Oftentimes, a developer will make a comment requesting additional specific information. If you do not provide that information, your report will eventually be closed.

If you’ve reported your issue against the wrong app, a developer may mark it as “Invalid”. If the developer knows which app you meant to report against, they may ask you to re-file against the correct app. However, if they do not you must find the correct app and re-file the report yourself.

If you’re reporting a “Wishlist” issue, like a feature request, a developer may mark your bug as “Opinion” or “Won’t Fix”. Developers are often open to discussion about these kinds of issues, but please do not harass a developer for marking your report this way.