While helping troubleshoot a issue in WordPress’s Woocommerce store front I noticed that orders with multiple shipping labels when purchased started failing the normal order shipping workflow because of a broken endpoint where multiple label ID’s were not being processed correctly by the store’s UI.

The endpoint being labeled I looked up its repo online. As I started looking to make sure no issues had been reported in the woocommerce-services repo for this same issue I noticed a disturbing trend.

As I look through the repos issues to see if anything already exists I noticed that a issue reported might have been the same issue I was having, but the issue was written so badly that it would have been impossible to understand what was breaking, and it hadn’t gotten traction, so I decided to write my own issue.

What Makes A Good Issue?

Tl;DR:

• Include a minimal, reproducible example (code or steps).
• Specify environment details (OS, browser, versions).
• Clearly differentiate bugs vs feature requests.
• Search for existing issues and link them.
• Describe actual vs expected behavior.
• Provide error logs or console output.
• Suggest possible solutions if able.
• Be respectful and patient.
• Follow up if maintainers request more info.

Some projects have issue templates that they want you to follow and if that is the case you should follow the template before submitting your issue.

If there isn’t a template try and think how a developer would read your issue. If you followed your own issue could you find the problem?

If you are a developer or can otherwise fix the issue yourself this would be a great time to offer your services and contribute to open source if possible though it definitely isn’t required.

Make your issues as clear and concise as possible. Take screenshots to show the part of a portal you are seeing a error in if this is your problem. If you are more technical try and dig in and find what is breaking or what change log entry update might have caused the bug. Try and change plugin versions and see what plugin versions have the same bug. Do a little troubleshooting and it will go a really long way to help the maintainers of the project not to mention it helps you as well because your bug or feature gets fixed quicker.

I like to make sure my issues are formatted correctly, so they read well. Below you can see an example of how I format my issues on Github and the kind of response the I get when doing this.

Example Of A Really Good GitHub Issue

Example Of A Really Good Response To Your Issue

What About That Formatting?

If you ever have written a README for a repo then the markup is exactly the same as that. if not, here are some examples to help you.

I have copied my issue with all it’s formatting here.

If you want to see the raw version of this same issue then click the button below

To see all of the Github markup you could use click the link below

I hope this helps you get the those bugs fixed up and feature requests passed through! Good luck.