/ Ollivander

Building a successful community-driven software project: part 2

This is a multipart article - link to part 1


3. Make it easy to report issues.
Yes, your software is got a bug. Never thought about it, didn't you? And here it is. 

Now, users shouldn't be forced to climb mountains in order to report it. You might not want it to be dealt with just in the discussion area, so a bug tracker is usually a good idea, but just like the discussion group, quick access should be allowed, either via anonymous issue reporting or using a backend supporting a decentralized authentication system. Remember, any bug reporter is doing you a favor! You shouldn't ask too much to them.

Many large open source hosting platforms, like github, launchpad, bitbucket, google code, are great examples of how you can achieve this goal pretty easily.

4. Make it easy to submit bugfix patches.
This is a big one, and I'm sure many people won't agree with me.

Sometimes a patch comes along a bug report, yet many projects have got some coding standards, and they don't accept patches that don't follow such standards. 

Whew. 

Many times, though, either the coding standard isn't really a widely accepted one, like PEP-8 for Python projects, but it's just how the lead developer likes to code, or many old parts of the codebase themselves don't follow such standard.

Hence, after I've discovered a bug in your software, I've debugged it, I've tracked it down and now I'm providing you a patch, you're rejecting it on a mostly cosmetic base because of some principles you alone chose to follow. Thank you very much sir, you're so nice to me. Don't call me by the way, I'll call you if I update my patch to achieve your great coding perfection.

The whole point is, your coding standards are your business. Never forget the Boy Scout rule - you don't have to make every module perfect before you check it in. Removing a bug is enough of an improvement to let a patch be accepted. If you don't want non-complaint code in your codebase just edit the patch - it should be easy for you - don't reject it and don't ask the reporter to edit it.

Of course there are perfectly good reasons to reject a patch. If it's a "worst hack ever" style of patch, or if it adds unnecessary complexity, provokes unintended side effects or changes a behaviour on which existing clients rely, just do whatever you think it's right.

There's another top rejection reason:  missing unit tests or insufficient coverage. Some projects with high coding standards require a unit test for each functionality and maybe 100% test coverage. It's perfectly fine, but there're issues with this choice.

Very often there're some legacy parts of the codebase that have got little test coverage; in order to achieve 100% test coverage the reporter might be forced to create a unit test that does not exist for some code that he has not written. That's a burden and most people will get discouraged.

Other times the overall design in some parts of the code does not allow for easy dependency injection, hence making it hard to create a good unit test which can really test the specific behaviour being patched, and the reporter might be able to reproduce the issue only with an higher-level, more integration-level-like test example.

In both those cases you should remember that the quality of your codebase is your business. You should not reject a patch from being applied because there're no unit tests if creating such a unit test is impractical and the fault is yours. Of course you can create a guideline for patch submission that says that you prefer the issues to be reproduced via a unit test, but don't make it a strict requirement. A patch without a test is better than nothing, you might just pick it up later when you've got some time and write a test for it.

Of course if a patch does not convince you for any reason and you don't get a unit test, just don't apply it - but don't be a template zombie - i.e. don't place policies ahead of people.

If you're unable to reproduce a problem because it happens in scenario you aren't able to test, try checking whether the patch causes any drawback to your supported scenarios. If it doesn't, you might decide to just trust the reporter.

Feature patches are a completely different story IMHO - when you accept something new in your codebase you should  be able to dictate whatever you want.

5. Reply to issues 
Reply to issues. Always. If possible, do it in a reasonable amount of time, which should be, in my opinion, ten days at a maximum. You don't have to take immediate action. Your reply could just be Investigating the issue or something like that. Remember the Inbox Zero approach to GTD: don't let unread, unaccepted bug tickets linger in your bugtracker! A lingering ticket is the first stop on the path to killing community support to your project.

The same approach is valid for issues with an attached patch - say something. Don't let issues linger unanswered.

And never, never wake up after a bug has been lingering for months just to ask the reporter if it "still applies"! This is terrible, I hate it when it happens. "Sorry, being too busy but did 37 releases of my software in the meantime, could you check if this still happens with the latest?". You're probably in a better position for verifying the issue - assuming that a way to reproduce it is provided - on any release, since you made them.

The next part will deal with APIs and public info for your project - see part 3