How to write a good bug report?

Last update: 11 August, 2016

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. That means you may run into a bug some day.
Of course, once found we want to fix the bug as quickly as possible.

Before we can write a fix, we’ll first need to reproduce the problem. Best case scenario is when we can just follow the steps you took and reproduce the problem on our own testing environment. Slightly 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, when 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 made a small checklist you can use when writing a bug report for us.

Bug report checklist

Environment Details

General Questions

  1. What did you expect would happen?
  2. What device/browser did the problem occur on?
  3. Do you have an (educated) guess as to the cause of the problem?
  4. Can you suggest a solution?
  5. Did you submit the bug in the proper place?

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.

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.

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 WP3.6 while WP3.9 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 Yoast SEO, 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 Fourteen. 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 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.

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?

The answer will vary greatly depending on your level of experience. And it’s perfectly OK to have no guess at all.

Can you suggest a solution?

Again, this will vary but if you’re a developer and can provide a solution, the issue may be resolved much faster.

Submit the bug report to the right place

Before you submit a new bug, please check if there already is an existing bug report for it. If so, it may be far more valuable to add to the existing one, than to create a new bug report.

And although it may seem obvious, we often see that bugs are reported in the wrong place. Sometimes we don’t even see perfectly written bug reports because of this. So here’s a short list of correct places for the Yoast plugins:

Yoast Plugin Correct place to report a bug
Yoast SEO GitHub
Yoast SEO Premium Premium Email Support
Video SEO Premium Email Support
Local SEO Premium Email Support
News SEO Premium Email Support
WooCommerce SEO Premium Email Support
Other Yoast Plugins GitHub

Was this article helpful? ·