Bug Reporting: A How-To

This type of bug report drives me nuts:

You have a critical bug! This crashes Java!

for (int i=0; i<10; i++) {
     cursor.next();
}

(I’ve never gotten this exact report and I’m not picking on anyone, it’s a composite.)

This doesn’t crash for me.  It doesn’t even compile for me because the variable “cursor” isn’t defined. If you’re going to use a variable (a function, a framework, etc.) in a code snippet, you have to define it. Let’s try again:

Mongo m = new Mongo();
DB db = m.getDB("bar");
DBCollection coll = db.getCollection("foo");
DBCursor cursor = coll.find();

for (int i=0; i<10; i++) {
     cursor.next();
}

Better! But this is probably crashing because of something in your database.  Unless it crashes regardless of dataset, you need to send me the data that makes it crash.  The basic rule is:

The faster I can reproduce your bug, the faster I can fix it.

Some other tips for submitting bug reports:

1. Make sure to include information about your environment.  The more the merrier.
2. If I ask for log messages, please send me the entire log.  If it’s been running for days and the log’s a zillion lines long, send everything from around the time the error happened (before, during, after).  Please, please, please don’t skim the logs, extract a single suspicious-looking line, and send it to me.  I promise that I’m not going to be mad about having to wade through a couple hundred (or thousand) lines to find what I’m looking for.  I would rather quickly skim a bunch of extra info than pry the logs, line by line, from your clutches.
3. If you are running on a non-traditional setup (e.g., a Linux kernel you modified yourself on a mainframe from 1972), it would be super helpful if you can give me access to your machine.  If your bug is platform-specific to ENIAC, it’s doubtful I’m going to be able to figure out what’s going wrong on my MacBook Air.

And, of course, flatter the developer’s ego when they’ve fixed the bug.  Not applicable for me, of course, but other developers like it when you give them a little “Thanks, you’re awesome!” biscuit when they’ve fixed your bug.

To my users: thank you to everyone who has ever filed a bug report.  I’m really, really happy that you’re using my software and that you care enough about it to submit a bug, instead of just giving up. Seriously, thank you. I have to give a shout-out to Perl developers in particular, here.  More than half the time, people reporting bugs in the MongoDB Perl driver actually include a patch in the bug report that fixes it!  I love you guys.