How to report a bug

Steps to reproduce. If you take only three words from this chapter, they should be “steps to reproduce”. In other words:

	Explain exactly what you did to make it go wrong.

	This is hugely important. The developer can’t fix your bug if they don’t know how to trigger it. Without steps to reproduce, your bug is the equivalent of your mum phoning you up and saying “My computer doesn’t work.” What doesn’t work, mum? “It just doesn’t work! Can you fix it?” Ngggh.

	(Insert joke here about “your mum”.)

	There is one place and one place only to report bugs, and that’s trac, the bug-tracking system (go figure). Never ever report bugs on mailing lists. That’s like standing in the town square and shouting loudly “SOMETHING IS SHIT AND THE BLOKE WHO DID IT IS AN IDIOT”. It doesn’t help get your bug fixed. You should tell the bloke in question in a less public forum which lets him keep his reports organised. That’s trac.

	Search trac first. Reporting the same bug that five people have already reported doesn’t help.

	Don’t jump to conclusions. If there’s even the slightest chance it might not be a “bug”, don’t call it a “bug”. Be humble and admit the possibility you, not the software, might be at fault. Don’t assume it’s a bug in one piece of software when, in fact, it might be a problem with the third-party service that software connects to. Or your Internet connectivity. Or the weird combination of software you have installed on your computer. Or something.

	The trac form lets you choose the priority for your bug. These should pretty much always be ‘minor’ or ‘trivial’. ‘Major’ is reserved for things that wipe out entire cities in the OpenStreetMap database without any user involvement whatsoever. ‘Critical’ is reserved for things that actually cause your computer to catch fire. ‘Blocker’ means your computer is ablaze right now and the fire exit is jammed. Your bug is not one of these. Really. It isn’t.

	If the developers want to reclassify the bug as ‘critical’, they will do. But creating a ticket with ‘priority: critical’ is basically saying “MY OPINION IS MORE IMPORTANT THAN ANYONE ELSE’S. YOU SHALL DO THIS IMMEDIATELY.” Unpaid developers tend to reply to this with “FUCK OFF.” (One of the nice things about being unpaid is you don’t get sacked for doing that.)

	Salutary lesson: there are at least two OSM developers who tackle bugs by starting with the “priority: trivial” ones first.

	Bug reports are just that. Reports of bugs. In other words, “this is what is wrong”. Do not be tempted to go onto the next stage, “and here is how you should fix it”. The developers are by their nature better at writing programs than you, because they’re developers, and you’re not. (If you were, you’d have fixed the bug already, right?) They know how to fix it better than you do. Don’t be so presumptuous as to tell them their job.

	This especially applies to user interface suggestions. Pretty much every single UI suggestion made in a bug report is a bad one and boils down to “You should present an alert box to stop the user doing this”, which never works, and if you don’t understand why, that pretty much proves why you shouldn’t put UI suggestions in bug reports.

	Don’t be patronising. Really. Don’t even think about accompanying, say, your ‘usability’ bug with a link to some Jakob Nielsen article you read once and only half understood. The developers are almost certainly aware of the issue: you don’t need to belabour the point. The reason they haven’t fixed it yet is that there are only so many hours in the day, and most of them are spent responding to clueless bug reports. (Oh, and don’t get me started on Jakob Nielsen.)

	Don’t file bug reports for software you don’t use. If you suspect there’s a bug in some other software, install the software and learn to use it - properly, not just to confirm your prejudices - before filing the report. Your comment won’t be remotely helpful otherwise.