I maintain a medium-sized open-source project. I welcome bugs and ideas via GitHub’s excellent “Issues” tab.
Some Issues are well-written, others are not. Strangely: Issues get resolved fastest are often the shortest – as little as 2 or 3 sentences. Doing it “right” is easier than I expected…
Psychology of Open-Source Support
If you want your Issue dealt with, you’ve got 4 barriers:
- Attention – does anyone read the Issue?
- Comprehension – can they mentally visualise the problem?
- Interest – do they care? can they be bothered to answer?
- Difficulty – how much will it cost them – effort/time – to change code and test it?
But most projects have no “employees” – just a loose bunch of users who sometimes Contribute.
None of them have “promised” anything; they only give code / respond to Issues when they feel like it.
That’s fair enough – but if you want your Issue answered, you need to tempt one of them into helping you.
Writing a good Issue, quickly
“How to report bugs effectively” is the great (but wordy) guide I originally learnt from. Here’s an Open Source TL;DR version:
- Any project with more than a few commits already “works” or people wouldn’t be using it. Other programmers probably aren’t seeing the problem you’re seeing, and you’ll have to show them how you’re triggering it
- The probability of someone answering your request is inversely proportional to how much up-front work they have to do before typing an answer. But this does NOT mean you have to do lots of work yourself – instead, ask a direct, precise question, or hilight a single, clear, concise problem.
- If a project is based around a particular document (e.g. SVGKit exists to open SVG files), or a particular service (e.g. a networking library that talks to servers) … it’s a waste of time to log an Issue without including the document/server-address/whatever that shows the problem: it’s obviously part of the Issue, it’s “what caused it”, so you must include it.
- If you can’t reproduce the problem on-demand … assume no-one else can either, and therefore your bug might as well be a figment of your imagination. You do not need to write a test-case (although that would be nice). But you do need to at least keep trying until you find a way to reproduce it quickly
- If it’s open-source, and you’re a programmer, there is no excuse for NOT running the debugger and seeing what went wrong. This is basic professionalism.
None of us are perfect. We all get it wrong, even when we know better. No-one will blame you for writing a “bad” Issue – instead, since they’re not being paid and have no Boss, they’ll simply ignore you. Or “Close” it and ignore you.
Things that get added / changed / fixed quickly
In 2013, on an Objective-C project, I noticed these things get resolved fastest:
RECENT ACCIDENTS
- Code I recently wrote, modified – or (as Maintainer) approved someone else’s modification
- The report doesn’t try to understand the problem – they see that something has gone obviously wrong in the debugger, or the app crashed – something severe that “you probably didn’t notice when testing or else you wouldn’t have approved the change”
- Because they ran it in the debugger and watched to see which variable was wrong they write a super-short Issue pointing out a simple code-level bug, e.g.: “I think there’s a typo in line 4 (I’m not sure what it should say, but it looks wrong right now)”
- …RESULT: normally, a maintainer can “quickfix” these in a handful of minutes
EDGE CASES
- Something that normally works fine – but a user finds a situation where it fails badly
- Critically: the person writing the Issue has worked out what the “edge” is (or at least: a close approximation)
- Best case (with a library that reads documents): the reporter has found “a 1-line document containing (X) always break” — that way, we have an isolated feature (X) to investigate and fix. I can ignore all other code.
- I’m happy if they merely find a line of code that “runs wrong in the debugger, but isn’t itself wrong” … because I can breakpoint that line, and work backwards to see what sent it the wrong data
CODE YOU OFFER TO WRITE YOURSELF
If a contributor is actively working on the code today, and sees your Issue, it may be quick for them to think about the Issue and act on it. In all other cases, it costs them time to mentally “context switch” to the code-base, and forget whatever they were doing.
- If you want something added, it is perhaps two times faster, but ten times less effort, for another programmer to support and advise and educate you … than it is for them to write it themself
- If you’re using the library anyway, then learning how to modify it to your desire is a skill you should be eager to acquire! If someone’s offering to teach you – bite their hand off! Take the offer!
SHOWSTOPPER BUGS
- Contributors are usually motivated by making sure “their” fork is included in Master, so that the rest of the community will fix, modify, and upgrade it in future.
- By contrast, maintainers are trying to promote the library and get more people using it. The reputation of the library is their biggest metric
- When a major bug appears – data-loss, or something that stops “ordinary” users from using the project – Maintainers will normally jump on it and try to get a band-aid (or a fix, if they have time), ASAP.
- You can ignore everything in this post if you find a show-stopper Issue; it will probably get a lot of attention. But it will also exhaust the maintainers, who have little time to spare – so it’s a good idea to help them out by making it easy anyway!
Hopefully this will help some of you to write shorter, easier – and yet: more effective – Issues for the projects you use :).
PS: Keith also pointed out: if you host your project on GitHub, you can make a CONTRIBUTING.MD file that will appear when anyone starts writing a new Issue (click for info).