Getting your problems fixed

Foreman is a specialized project for data centers. If you happen to have a bunch of servers, it helps you deploy, provision, upgrade, and manage them; it works with virtual servers in the cloud as well. Tomer Brisker is one of the developers, but his talk was not specifically about Foreman. Instead he spoke on the general issues of how to deal with the problems you're having with a piece of free software, whatever that software might be.

So, Brisker said, you're a user; you've hit a bug, or maybe you have a feature request. What should you do now? Step 1 is not to panic, which was accompanied by a highly-entertaining slide (seen at left; full slides [11MB ODP]) of someone panicking. This slide cropped up quite a few times during the talk.

Maybe it's not a bug, it's just a misconfiguration issue. Maybe it's a known bug, with a known workaround. The best place to start here is the manual. Many projects don't have great manuals, but plenty do, and if your project has one and you don't read it, you may be setting yourself up for failure.

If that hasn't helped, get on IRC. Nearly all projects have a channel, and it's the fastest way to get in touch with the developers, who probably want to hear from you. Brisker explained how a user once came on IRC and complained about Foreman pages being slow to load. He couldn't reproduce the problem, but he was managing a small set of virtual assets on his development box, while the user was managing several thousand servers in a big data center. Over the next two hours, Brisker produced a series of patches that the user deployed, tested, and reported back on, after which time they had reduced the user's page load time from twelve minutes to seven seconds. User, developer, and the wider community all gained from that interaction.

If IRC doesn't work out, try mailing lists; most projects do still have them. They can be slow (or at least high latency), but they reach more people, and they're archived. Moreover, they don't suffer from the problem that all the developers are in distant time zones and so not on IRC when you're having your problem. Finally, they allow for a fuller and more measured statement of a problem.

Brisker begged that, if you post to a mailing list, and you later find a fix (whether via the manual, IRC support, personal experimentation, or any other way) you post again to summarize the fix. Few things are more annoying than searching list archives for a problem to discover that, apparently, lots of other people have had the same problem, and then they all died.

If you've still got the problem, it might be time to panic, though it won't help. Instead, you should fire up the project's issue tracker; nearly all projects have one, be it Bugzilla, GitHub issues, Redmine, or something else. Search before posting; not only is it polite not to waste other people's time, you'll get a faster resolution if your problem has already been found and fixed.

If you find you have to create a new issue, try to be as precise as you can and give as much detail as you reasonably can; don't be vague, don't rant, don't write a letter, and don't suggest rewriting the whole project from scratch unless you're prepared and qualified to do it. Do write in English unless the project's main language is clearly something else. Don't forget to include version numbers and platform details. If at all appropriate to the error, give a stack trace. If you're asking for new features, give context: about what are you trying to do; how will the proposed feature help you to accomplish this?

If none of this gets you a fix, remember that it's free software and that you can fix it yourself. If you do, don't be afraid to submit your changes to the project. If you do that, follow the coding standards; there is no right answer to spaces-or-tabs, but whatever the project already does, you should copy.

If you're submitting code directly to a project's repository, commit messages should be substantive; helpful ones are even better. Don't forget that you can add a screen shot to a commit on GitHub; sometimes a picture is worth a thousand words. Tests are very important; code that includes tests is monitoring itself for correct operation. That helps both future-proof it against changes elsewhere and gives code reviewers warm fuzzies, which helps acceptance of your changes. If you can't code, but you find a workaround, contribute it to the project documentation.

Finally, at all times, be polite and patient. Many maintainers are volunteers, and even the paid ones have a lot on their plate. Finding bugs is crucial to fixing them, so the user-developer interaction is vital to improving free software. With these few simple ground rules, it can even be fun.

[Thanks to the Linux Foundation, LWN's travel sponsor, for making this article possible.]