How to write a good bug report?

Despite all the measures, such as code reviews and automated unit-testing, we take to create the highest quality code, it is virtually impossible to make software completely bug-free.

If you do find a bug, we want to fix it as quickly as possible,

Before we can write a fix, we’ll first need to reproduce the problem. The best case scenario is when we can just follow the steps you took and reproduce the problem on our own testing environment. We love when people send us pictures and videos of the problem (as it makes it really easy to replicate). It is less optimal is when we have to rebuild your environment, for example by matching your PHP version or installing the plugins that (may) cause the problem. Worst case scenario is when we cannot reproduce the problem at all, as this means we won’t be able to fix it.

So, if you encountered a bug while using our plugin, we really need your help. You are the only one who knows how to reproduce this bug, so the better you help us, the better we’ll be able to reproduce and fix it. Therefore we’ve made a small checklist you can use when writing a bug report for us to help us as much as possible.

Bug report checklist

1 Steps to reproduce
As said, we’ll need to reproduce the problem you encountered. The very first we need to know is what you did/clicked/typed to produce the problem. Generally speaking, there are three ways to provide this information which are not mutually exclusive;

  • Written step by step description; explain every step you took in a clear and unambiguous way. Numbering your steps really helps when communicating about the problem you encountered.
  • Screenshots; take a screenshot of every step you took. A free program like Skitch can be very handy to add notes or markers to your screenshots to point out anomalies.
  • Screen recordings; make a video of your screen of every step you took. A free program like Camstudio can do this for you. Sharing the video can, for example, be done via Youtube or Screencast.

What did you expect would happen?
Most of the time you weren’t searching for a bug, but trying to do something on your website. Please explain briefly what behavior you expected when the problem occurred.

Error messages
We’ve tried to build in as many error messages as possible, so both of us get informed when something is going wrong. If you saw an error message, please copy it fully and/or make a screenshot of it.
If you know your way around websites, you may be able to take a look at the (JavaScript) console to check it for errors. When there are any, please copy them completely and put them in your bug report. Or if you expanded the message in the console, you can take a screenshot and send that to us. Error messages can be really useful when we try to pinpoint a problem, as they give valuable information about the expected location of the cause.

4 WordPress Version and Plugins
There are two main reasons we need to know the version of your WordPress installation. The first one is quite simple; if you’re using an outdated version (for example WP4.2 while WP4.7 is current), we will require you to update to the current version. The second reason is that WordPress Core changes with each release. So a problem may have been fixed/caused in a later update. Therefore it may be necessary for us to mimic the WP version you’re using.

We would also like to know if you’re running a multi-site, as some problems may be specific to that.

Your WordPress installation consists of WordPress Core and usually one or more plugins. Unfortunately some plugins conflict with each other, therefore we want you to test if your problem still exists when you’ve deactivate all other plugins. For example; when the problem occurred when using MonsterInsights, disable all other plugins and repeat the steps (1. of this checklist). If that solves your problem, reactivate all other plugins one-by-one. After every plugin you reactivate, test for the problem again. This should help you pinpoint the plugin conflict.

If deactivating plugins doesn’t solve the problem, please switch to a standard WordPress theme, like Twenty Sixteen. Does that solve your problem?

(Web)server details
Problems can be related to a certain setup of your (web)server. Therefore we would like you to fill in as much as possible in the following list:

  1. Operating system of your webserver
  2. Webserver in use (Apache, NGINX, IIS, other) and what version
  3. PHP Version and (extensions if applicable)
  4. MySQL Version

What device/browser did the problem occur on?
What device were you using when the problem occurred? What operating system is it running? What browser were you using? Does the problem also occur on another browser and/or another device?

Do you have an (educated) guess as to the cause of the problem?

Can you suggest a solution or how it should work instead?

Finally, submit it directly to our support team via our contact form.