Working on an open-source project teaches you a few things about dealing with software developers, and reporting bugs. I've been in the open-source world for a long time, and I remember when I first started out as a user of software, I felt glad to even have access to these tools at all, and I felt a reluctance to "bother" the developers with issues if I wasn't sure it was only me.
The problem is, issues are a bit like Schrödinger's cat: they don't exist until the developer knows about them.
Since I've become a developer of open-source software and seen things from the other side, I have one request: err on the side of opening an issue. There's nothing I love more than having an issue opened, and being able to fix it, and tell the user their problem is solved. It's that kind of feedback loop that is one of the best parts of developing software without a marketing and sales department sitting between you and your users.
So without further ado, I'd like to point out a few comments in this vein. Note that when I say "issue," it could be anything: a showstopper bug, an annoyance, or just a new feature you wish the software had.
- Always Open an Issue
- Sure, sometimes it's a pain to figure out where the issue reporter link is, and create an account, and validate your email, and figure out what component it goes into... but don't worry about it. If you get it in the wrong place, they'll know where it belongs and (hopefully) triage it. But if you don't open that issue, they may never know it's a problem.
- Don't Worry If It's a Duplicate
- Of course, you should always try searching for your issue first, maybe someone else has reported it. Make a comment if someone has. But if you can't find it, don't worry that it might be a duplicate, go ahead and open that issue. As a developer, I'd rather close a million duplicates than to never know about the issue in the first place.
- Don't Just Describe the Issue, Describe What You're Trying to Do
- It may be that the issue you're trying to solve is meant to work a different way, or is part of another feature you haven't used yet, or has a workaround. Make sure when you describe the problem you're having, also describe what you want to accomplish.
- A Closed Issue is Not an Ultimatum
- This is a corollary to "describe what you're trying to do." Just because an issue is closed does not mean it is closed for discussion. Sometimes the developer doesn't realize what you're trying to actually do, or the original issue was described in a way that doesn't make it clear that the real issue is elsewhere.
For example, OpenNMS supports creating a "path outage," which describes how particular nodes are related. There was an issue opened that said if you created a path outage, it would be wiped out when using Provisiond. It was closed, saying that you create path outage relationships with the "parent-id" tag in the provisioning group file. What the issue did not say is that these manually-created path outages were created through the UI. So the real issue is that the web UI path outage editor is not Provisiond-aware, and the issue should be reopened.
- It's Better to Be Too Verbose than Not Enough
- Configuration files, logs, output from `dmesg` or similar, anything you can add that makes it easier to diagnose the problem. It's a lot harder to fix a problem with a one-line error message than with 200 lines of context telling you what the software was doing just before the error. The more information you give, the more likely it is the developer will be able to figure out what's going on when the issue happened.
Does this mean your issue will be resolved quickly? Not necessarily. Everyone has their own set of priorities, and their own time set aside for working on issues. I can say that a good issue report, with a lot of detail and a good description of what you're trying to accomplish, will get a lot more traction than a 1-line report saying "it doesn't work," and it will get a heck of a lot more traction than no report at all. To paraphrase Wayne Gretzky, you miss fixing 100% of the issues you never report. 😉
