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. As a consequence, sometimes, you may run into a bug. Of course, once you find it, 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 some of our plugins, 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

• Steps to Reproduce
• Error messages
• WordPress Version and Plugins
• (Web)server details

General Questions

• What did you expect would happen?
• What device/browser did the problem occur on?
• Do you have an (educated) guess as to the cause of the problem?
• Can you suggest a solution?
• 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 of WordPress, 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, a theme and usually one or more plugins. Unfortunately, some themes or plugins conflict with each other, therefore we’d advise you to test if your problem still exists when you’ve deactivated all other plugins and switch to a default WordPress theme. You can use our conflict check guide to determine if your issue is related to a plugin/theme conflict.

(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?

There are a few questions that may help us get to the root of the problem. Questions like: 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

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