Creating Issues

February 13th 2012

I wanted to take a moment to talk about issues, specifically Github issues. I feel like over the last few months through my involvement in the open source community I’ve seen tons of interesting approaches to Github issues and thought it might be valuable to let you know in my eyes what works well and what works less well.

To begin, I think there are three types of issues (at least three which i see most frequently). These include: bugs, feature requests, and “can you help me, I’m stuck”. While generally I try to help the people who are simply just stuck, I’m not going to spend too much time on that now. However, the best place for that sort of help is generally going to be in mailing lists, IRC, or twitter.


By far bugs are the most common issue I see… and for that, thank you! This means you’ve ran into a problem with a library and you’re coming to let the maintainers know about it. <3!

Unfortunately, of these bugs i see tons to the effect of:

Modals don’t work on my site myhugesitewithtonsofcrazyjs.com. pls fix.

While I’m sorry to hear this, there isn’t really much you’re giving us to work with in terms of figuring out what’s wrong.

Instead, the first and single most import thing for you to do when filing an issue is concentrate on isolating a demonstrable problem. The goal here is to be able to provide the most mind numbingly simple and easy to reproduce problem as possible. Often times large projects are maintained by just a handful of people; each person processing hundreds of issues. Because of this, clearly and simply communicating your problem means everything.

Opening an issue is really about making a case for your bug. You need to convince the maintainer that something is indeed wrong and the simplest way to do this is through examples.

Stop pasting code!

I think peoples first instinct when filing an issue is to paste all the code they have which may be related to the problem.

This is the saddest of times for someone who is trying to debug your problem because it means they have to read through alllll of it! And engineers are lazy – you should know better.

Pasting code is not providing an example. It’s not isolating a problem. It’s not demonstrating anything. It’s just sad times.


Instead, in my experience the hands down best way to do communicate your problem is by enlisting a tool like jsfiddle (or jsbin or dabblet or whichever your prefer…).

If you’re unfamiliar with jsfiddle, it’s “a playground for web developers"… (just go try it…)

The great thing about using something like jsfiddle is that it forces you to reproduce your problem in a new, isolated environment. So many times I’ve asked “would you mind please providing a jsfiddle” – and simply in creating the fiddle, the person filing the issue has stumbled across something they themselves were doing wrong.

That said, creating a jsfiddle also makes it really easy for the person debugging the problem, as they can jump right into the experience, checkout the code, and find a solution. It’s the best!

Unit Tests

If you’re feeling like a boss and the maintainers of the project you are opening the issue against are using unit tests (they should be!) – then you could alternatively create a failing unit test and submit it as a pull request along with your issue.

This is also the best choice for issues which aren’t being opened against front end projects (as they can’t be demonstrated with jsfiddle).

Unit tests look something like this and are fairly painless to pick up if you’re unfamiliar with them.

Admittedly, this is the most time consuming way to file an issue… but will seriously make any maintainer love you forever.

Again, it’s all about isolating and demonstrating the issue – here with the added benefit of saving the developer time in writing regression tests.

Pull request?

If you’re feeling really confident you can go ahead and try to provide a patch in the form of a pull request (again, please do not paste code…). That said, in my experience I’ve found it best to coordinate the problem and solution with a maintainer before putting in the effort of actually writing the code out.

While you may think you’re killing it by rewriting all the things to make something work &ldq