Posted on by & filed under tools.

Some of the most useful tools in ebook development are open source. Calibre and epubcheck especially come to mind. If you find a bug or want to request a feature, what are the best ways to ensure your needs get attention?

Submit a patch

Of course the holy grail for the lazy open source developer is when someone submits a “patch”, or a fix for the issue. That means you don’t have to do any work because someone fixed it for you. Hooray!

In practice, this is pretty rare except for the most active open source projects. Many of the users of these tools aren’t programmers, or even if they are, they don’t have the time to go digging through unfamiliar source code to find the source of the problem.

Post a bug, don’t send an email

All open source projects have public bug trackers. This is probably the best thing about open versus closed source. Do you know where to submit a bug to Adobe Digital Editions? I don’t. But I know where to send an epubcheck bug.

It’s common courtesy to quickly scan the bug list to see if your issue has already been reported, but everybody understands that sometimes this is inconvenient. The Calibre bug tracker has more than 500 open tickets. Nobody expects you to go through them all, and it’s easy for the developer to close duplicates. But if it’s a small list like epubcheck’s, do check first.

Reserve sending emails to the developers for when you actually want to open a dialogue, or need to discuss something privately.

Submit a test case

When you post a bug, the best way to ensure your bug gets attention is to submit a test case. In the case of ebooks this is pretty easy — submit a sample ebook that exhibits the problem.

A good test case should be as minimal as possible. Ideally it should have only the content necessary to exercise the bug.

Generating a test case can be time-consuming, but remember you’re asking for someone else (usually a volunteer) to take anywhere from 15 minutes to several hours to fix your issue.

Consider the human

The key concept here is that submitting a bug is a social interaction, not a technical one. You want to convince a developer who is probably busy and distracted that your bug is worth their time.

Open source bugs are often fixed in the short intervals that people have between other tasks. You want to convince the developer that the bug can be fixed in that timeframe. Providing a clear bug report, being polite, and providing a test case are the best ways to support that assertion, even if in the end it turns out to be a tough problem that takes hours to fix. Hook them with a clear test case!


2 Responses to “How to get your bug fixed”

  1. sokolov

    What do you mean? I’ve heard that it can be very effective to send an e-mail (preferably to a widely-distributed mailing list, if there is one, or just to the developer otherwise) that says “program X is broken. I tried it and it doesn’t work.” If no response is forthcoming, it is often helpful to send a follow-up message. Something like “are you even listening?” can really get the developer’s attention.

  2. bowerbird

    > You want to convince a developer who is probably
    > busy and distracted that your bug is worth their time.
    this is why it can really help your case out if you state
    “i’m sure it will only take a minute or two to fix this.”