How to effectively report bugs on GitHub (and what not to do)

A lot of open source WordPress plugins and themes have a GitHub repository, usually on the side of their main download website. Most developers also use the issues available in each repository to keep track of issues. It’s often not clear what kind of issues should go in there, but I think almost all developers will agree with me that it’s not the best place for support. So I have to close lots of issues that are actually support requests.

I even have a snippet nowadays that I use to close an issue (more on this below):

This is not a support channel. You can post this kind of questions in our public support forum: http://wordpress.org/support/plugin/woocommerce or in case you are a WooThemes customer via our support portal: http://support.woothemes.com

We have a lot of issues being opened on our GitHub repository, that are just support issues. Requesting support is tricky enough already, but filing a proper bug report is even more complicated. People often ask what the difference is between reporting a bug and asking for support. In the end, both are aimed at solving a problem.

What is requesting support and what is a bug report?

A support request can actually be a bug report, but not the other way around. The purpose of resolving a support ticket is to solve a problem for one user. A bug report is to explain a bug in the software, to make the software more stable. Let’s take a look at two example and where these two overlap.

This is an example of a (actually surprisingly well structured) support request:

Error when using plugin X and Y
I just activated plugin X and now plugin Y shows this error: …. How can I resolve this?

Here’s the same problem, explained in the form of a bug report:

Conflicting function name in plugin X and Y
Both plugins X and Y use function name … and this results in the error: …

The support request and the bug report are both aimed at resolving the same bug. If I would read the support request, as a support employee, I would probably try to debug this first. Eventually I would figure out the cause of the problem and would report the bug to the developers in the form of the above example bug report.

When a user asks for support, without knowing the cause of the problem, it’s a support request. When it turns out that the problem is in fact a bug, the support request becomes a bug report and can be treated as such.

How to write an effective bug report

Most developers will close a report when it’s actually a support request and the issue tracker is clearly not intended to be used for support requests (like we try to explain with our CONTRIBUTING.md file). So you want to make sure your bug report is actually a bug report and contains everything required for a developer to fix the bug you are reporting.

It’s not that developers don’t want to help you with support issues, but GitHub just isn’t the right platform for support. That’s why my snippet always contains links to the platforms where the user will get support.

Here are the basic requirements for a good quality bug report:

  • The title explains the issue in just a couple words
  • The description is detailed enough and contains at least:
    • steps to reproduce the issue
    • what the expected result is and what actually happens
    • the version of the software being used
    • versions of relevant external software (e.g. browser and operating system)
  • Explain what you’ve already done trying to fix this issue
  • The report is written in proper English (given English is the main language of the software)

The more detail included in the bug report, the easier (and quicker) it is for the developer to solve the bug. And that’s what we all want, isn’t it?

Examples of good (and bad) bug reports

Just for the fun of it, let’s have a look at a really poor bug report first:

Bug
I just uploaded it and it doesn’t work. I can’t create products. Please fix.

As funny as this might seem, there are actually people trying to get support (because this is not even a bug report) like this. It might have the format of a bug report and it’s posted on GitHub, but that’s as far as it goes. Now let’s have a look at the same bug report, only now properly structured and containing all the details required:

Parse error when creating new products (version 2.0)
I just activated this plugin (version 2.0) on a fresh WordPress 3.7.1 install. When I now try to create a new product, the following error shows: … This didn’t happen in the previous version, which I have just confirmed using version 1.9 on the same fresh install.

This second example is only three times as long as the wrong one-liner above, but it contains so much more information and is actually something a developer can reproduce. It also indicates that this bug was introduced in the latest version and also with what version of WordPress this bug occurs.

Let’s make GitHub a better place

Trust me, I hate closing an issue in our GitHub repository when it’s someone desperately ask for help. I will do it anyway, because otherwise I will be opening the flood gates and basically allowing anyone to request support on GitHub. What I do try to do is (aside from posting my snippet) to point the user in the right direction. So I will point to some documentation or a tutorial describing the issue the user is dealing with.

Let’s make GitHub a better place and use it for what it’s really good at. Bug reports are always welcome in our repository (although I prefer having no bugs at all 😉 ), but please try to give us all the information you can.