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 repr