How to report issues with WordPress plugins
Since I’ve released a WordPress plugin that’s been attracting a fair amount of attention, it’s inevitably had its share of users who have reported some problem or other. Most people find that everything proceeds fairly smoothly, but inevitably there will be those who, for one reason or another, simply can’t get it up and running. So I thought I’d put down some tips on what to do if you encounter a problem, and how best to go about reporting it.
This advice is intended to be fairly general, and not specific to any of my own plugins, and though different developers may have slightly different expectations, it should come in useful irrespective of which plugin you are using and who wrote it.
1. Make sure that you’ve read and understood the instructions.
This may sound obvious, but amazingly, some people don’t. Check that your version of WordPress is supported (most newer plugins these days require version 2.0 or later, and some even require version 2.1). Check that you’ve understood correctly what the plugin does, what all the configuration options mean, and whether or not you’ve overlooked something. There may also be some known issues or bugs with the plugin, so you should check to see if you’re up against one of those. It also helps to read the comments left by other users: they may be able to shed some light on the problem. A search of the WordPress support forums may also help.
You don’t have to trawl the whole Internet or even the whole site, but if you at least show that you’ve looked in the most obvious places, it helps a lot. If there’s anything you don’t understand, by all means say so, but indicate exactly what it is that you don’t understand, rather than simply saying “I don’t understand the instructions.”
2. Check to see if there’s a conflict with another plugin.
There are thousands of WordPress plugins out there, and it is simply not possible to test our creations against all of them. Consequently, there is always the possibility that your newly installed plugin could be conflicting with one of the others that you have been using.
Checking to see if this is the case is fairly straightforward, though it’s a good idea to back up your WordPress database before you do so in case anything goes wrong. Disable all your other plugins and switch to the WordPress default theme. This may or may not fix the problem. If it does, switch your theme back and then re-enable the other plugins one at a time until the problem reasserts itself. When you do this, the conflict is between your new plugin and the last one that you re-activated.
You should let us know which other plugin or theme, and which version, is causing the problem. Tell us where to get it too, and make sure that the link to its home page still works. There is little or no incentive to ensure compatibility with a plugin or theme that has vanished off the face of the web and is no longer being maintained.
3. Check to see if the problem occurs on other computers in other places.
If you can, check to see whether or not you get the same problem on a different browser on another computer. You don’t have to check every permutation of plugins and so on, but if the problem occurs in one place and not another one, we’d be interested to know.
4. Make your feedback clear and specific.
Here is an example of a bad question:
I tried your plugin. I can not get it to work. What is the problem?
This haiku is worse than useless because it tells me nothing, yet I have to spend time reading it and deciding whether to respond to it or report it as spam to Akismet. If you’re lucky, you’ll get a response along the lines of: “I haven’t a clue. I am not a mind reader. Please give more details.” If you’re not, you’ll just be ignored and your comment will be flagged as spam.
By contrast, here is an example of a good bug report:
I’ve installed version 3.14159 of the Happy Pi Day plugin and I’ve found that my users are getting a Blue Screen Of Death when they visit my website on the fourteenth of March if they’re using Internet Explorer on Windows Vista. I’m running WordPress 2.1.3 on PHP 4.4.4 and MySQL 4.1. I’ve tried disabling all my other plugins and switching to the WordPress default theme, but the problem still persists. There’s an option on the plugin page that says “Einstein’s Birthday Mode” but I didn’t understand from the documentation what that is supposed to do, so I haven’t tried changing that.
You can see the problematic page at http://www.example.com/happy-pi-day/.
This is much better because it gives us a lot of useful information in clear, unambiguous terms.
At an absolute minimum, you should state:
- what you expected to happen;
- exactly what actually happened;
- the exact text of any error messages;
- the steps needed to reproduce the error;
- which versions of WordPress, PHP, MySQL and the offending plugin you are using.
You should also give as much additional information as you have been able to determine in your troubleshooting steps above:
- which browsers and operating systems are affected on the client side;
- whether you have found a conflict with any other plugins or your theme;
- anything about the documentation that you didn’t understand;
- where appropriate, the URL of a blog or post where the error can be seen in action.
Remember that you’re aiming for clarity. Write in plain English, in whole sentences. Read your report back to yourself to make sure that it’s clear and unambiguous. Don’t post guesswork as to what you think the problem might be: report the symptoms of the problem — i.e. exactly what you did, exactly what happened, and exactly how reality deviated from your expectations.
Many plugin authors — myself included — work on their offerings for free. This means that the amount of time that we can spend supporting them is strictly limited, and unless you are one of our paying clients, we have to triage bug fixes and support issues that come our way, sometimes pretty aggressively. Inevitably, it’s the queries that provide us with the most helpful information about the problem that are likely to get the most (and quickest) attention.