How to do Open Source
I've been working on open source projects for a few years as both a contributor and maintainer, and at times I've run into some annoyances that I think merit a blog post. Below are a few suggestions for working on open source: from both sides of the keyboard.
AS A CONTRIBUTOR
Make useful changes. Don't just make a bunch of aesthetic changes to somebody's code and expect the author to apply your commit. You should send someone a patch only when you actually fix or enhance something.
Preserve the author's style. Try to use the maintainer's style when you
write your code, so that your code looks like theirs and the project maintains
some consistency. If they put braces on the line after an if and you like
them on the same line, just grit your teeth and use the author's style rather
than yours.
Don't introduce dependencies for small changes. Unless you're implementing a major new feature, don't introduce new 3rd party dependencies. The maintainers may have reasons why they have avoided using a particular library. If you think it's necessary to do so, ask the project maintainer first to make sure they'll still be willing to apply your changes.
Don't mess around with project setup files. Make your changes to the project's code, not its "meta" files. I personally find it annoying when someone sends me a patch that includes unnecessary changes to my project's Rake tasks, gemspec, etc. Only send a patch like this if it includes some extremely useful changes or fixes something that's obviously broken.
I've received pull requests from people that did only a little more than fix a typo and eliminate whitespace, yet added themselves as a coauthor in the gemspec. Seriously, don't do this.
Don't send one useful feature plus a bunch of junk. Many times I have gotten patches from people that include code I really want to use, but also include a bunch of unnecessary changes, such as tweaking method names, renaming tests, etc. At least with Git it's usually possible to cherry pick the changes you want to apply, but it's much nicer if you don't have to. Make your patches focus on one thing. The last thing I want to get is a patch titled "Adds feature x (plus some cleanups)."
If you really can't resist, at least break your changes up into a bunch of small commits so that the maintainer has an easier time choosing what to apply and what to reject.
Unless the docs really suck, don't "revise" them except to make substantive additions. A few times I've received pull requests from people who "improved" my documentation, but their changes introduced spelling errors and ungrammatical sentences.
I used to teach college English, and while I know my documentation and writing are far from perfect, I'm a little particular about some things. Unless you know you're a pretty good writer, and the docs obviously need some attention, you're usually better off sticking to improving code and just documenting your additions.
Always add tests for your new code. If for some reason the project isn't already using tests, it's probably not worth hacking on yet anyway.
AS A MAINTAINER
Don't create unecessary bureaucratic processes for submissions. Having a few ground rules is OK, but I've seen tiny projects that devote more words in their README explaining how to submit a patch than to project documentation. Unless you are running a large project, don't expect to be flooded with tons of patches. Consider yourself lucky and honored if your code interests another developer enough that they use it and want to improve it. So keep the barrier low and don't ask too much from your contributors.
You may get patches from people who are not as skilled a programmer as you are, but that are still useful. Receive them with gratitude even if you can't use them. If necessary, fix whatever deficiencies they have, or work with the developer to help them get the patch in shape.
Don't be a jerk. Just because you're running an open source project that a few people like doesn't mean you're suddenly a rock star. When people try to contribute, be nice to them. If they are not following the guidelines you want them to follow, helpfully and politely explain the "right way" to do it. Here's an example of what not to do.
Here, some guy has a valid feature suggestion for Rails but has made it in the wrong place. Rather than tell him to ask some place else and give him a link, the maintainer can't resist taking a shot at him: "LH is a unicorn-free zone."
If you're a big project like Rails you can get away with this (though I still don't like it), but I've seen people cop this same snarky attitude with their tiny Github projects with 4 followers. This is a great way to turn people off to your project who might otherwise be willing to offer significant help for free.
Make your code easy to hack. Include well-organized tests with good names that explain what's being tested. Make it easy for someone to add new tests for the features or fixes they are implementing. It's easier to insist on patches including tests when your existing tests are in good shape.
Also, document your code well. Don't just document your public API, document private methods as well so that a developer hacking your source code can easily figure out what they do. Don't go overboard – your code should ideally be as self-explanatory as possible – but sometimes a sentence or two explaining the purpose of a private method can make it much easier to read code.
Be grateful. When people invest their time and energy into improving your code and ask for nothing in exchange, the least you can do is thank them and give them credit.
Maintain a project changelog, and give the person credit for their changes there. If possible, it's also nice to include a link to their blog, Github profile, or something of the sort. If someone does very significant work on your project, consider adding them as a coauthor even if you don't give them commit access to your repository.
What annoys you?
That's all I can think of for now. What annoys you as a developer or maintainer doing open source? Let me know in the comments.
Published