If you contribute to an open source project, you have my gratitude. It’s often a thankless job, unless you’re working on very high profile projects, and even then. Most people don’t become rich and/or famous because of their work in open source, and you sometimes have to deal with obnoxious project maintainers who don’t appreciate your time. (Don’t worry, I’ll be writing a post about how to maintain a project without being a dick soon.)

I’ve learned more about how to be a good OSS contributor by being a project maintainer than I ever did by being a contributor, and I want to share some of it with you in the hopes that you may become less of a dick, or at least give some consideration the next time to open that ticket or submit that pull request.

Proactively look for contributing guidelines

This seems obvious, but you’d be surprised how many pull requests I get from people who didn’t bother to read the very detailed and specific contributor guidelines I wrote. Check the README and look for a Contributing.md. Maintainers will usually tell you how they want things done, including what branch to submit pull requests on, what unit tests should be included, and so on.

As maintainers, we truly do appreciate your time, and are incredibly grateful that you care enough about our projects that you want to help, but when you don’t follow our guidelines, you can literally create hours of additional work for us (to the point where it would have been faster for us to just write the code ourselves). Most of us have regular jobs (and, you know, lives and stuff) on top of managing our projects, so that shit gets old fast. Your time is valuable, but so is ours.

Find out whether the maintainers prefer squashed commits…

… and even if they don’t, don’t commit a bunch of bullshit. I don’t require squashed commits, as I tend to prefer more granular history of changes, but this is an actual pull request I got.

Screen Shot 2014-11-05 at 5.23.49 PM

All of those commits were for a single file. One. File.

When you create a pull request, I have to sort through all of those changes to figure out what you did, so I can determine whether it’s a viable PR. Before I even pull down your branch to test it locally, I look through your changes.

Commit log messages are not intended to track every experiment, every line break, every formatting change. Make your changes, test locally, then commit and submit your pull request, or squash your commits before you submit your PR. I don’t need to watch in real-time how you learn how to code.

Use feature branches, every time

Unless the contributing guidelines ask for something different, always create feature branches, and stick to them. Don’t sneak additional changes into your feature branches.

This is (only a partial!) screenshot of one pull request I got. There were over 100 commits that touched hundreds of files. (This is a reasonably small project. Hundreds of files is a lot.)

Screen Shot 2014-11-05 at 5.39.40 PM

Unsurprisingly, when I pulled this branch down to test it locally, everything blew up. I had to delete my own local install and re-install my own project from scratch.

When you combine hundreds of changes and fixes into one PR, it makes it impossible to figure out which change broke something. Reducing the amount of time (and effort) from defect creation to defect detection matters.

If I can’t test your changes, I am not going to accept the pull request. If your stuff breaks my stuff, I’m not going to accept your pull request. If I as the project maintainer can’t get your shit to work, there is zero chance of my users (who are less familiar with my software than I am) will be able to. To think otherwise is simply crazy.

Start small

If possible, start by making some small fixes or features. This lets the maintainer get to know you and your coding style, and lets you get to know the maintainers. I once made the mistake of spending 6 hours on a pull request (upgrading the version of Bootstrap from 2 to 3), only to have the maintainer deny the pull request because he’s not accepting any PRs right now. Ugh. Don’t be me. That sucked. (I ended up forking the project and just maintaining my own version.)

Have a shred of fucking empathy

Real people wrote this software. Actual human beings. Treat them like human beings. Don’t make demands, don’t waste their time, and try to make their life easier. They’ve made your life easier by writing the software in the first place. Extend them the same courtesy. Ask them what they’d most like help on. Let them know that you’re working on something so they don’t start working on it without realizing someone is already on it. Be patient.

Most open source projects are a labor of love. People care about the stuff they work on. That human being wrote software, and then went the extra miles to make it available to help other people with the same problem – and then agreed to take on the ongoing (ceaseless) support for their users.

Don’t tell the maintainers how their software should work

Most likely, the maintainer wrote the software to solve a very specific problem they were having. That problem may not be the same as your problem. Explaining your use cases is enormously useful, as we sometimes don’t even realize the funky-ass ways you’re using our stuff – but don’t assume that your use case is more important than anyone else’s.

As maintainers, we have to walk a delicate line of creating software that’s flexible, but not so divergent from the intended purpose that it could do literally anything.

Suggestions are awesome and encouraged. Subjective criticisms without a pull request or that relate to your own narrow use case are just shitty.

A maintainer’s job isn’t just managing the codebase. In  many cases, they are sort of like the CEO of the code, in charge of not only the physical code, but also the project’s heart and soul.

Figuring out what features make sense for solving the problems that specific piece of software is meant to solve is harder than it seems sometimes. Managing multiple contributors with different personalities, coding and interaction styles can be a lot of work. It’s extraordinarily rewarding, and I recommend that everyone do it if they can, but it’s important to understand that they are responsible for all of their users, not just you.

When you get better at contributing, you’ll find your pull requests are accepted much faster. Help us to help you.

ssd-virtual-servers-banner-468x60

Advertisement

468x60_makemoney
local_lolcat-20100927-135536
Previous post

Project Localization Without the Pain

owl
Next post

The Hardest Part of Running a Startup Isn't What I Thought It Would Be

snipe

snipe

I’m a tech geek/dev/infosec-nerd/scuba diver/blacksmith/sword-fighter/crime fighter/ENTP/warcrafter/activist. I'm the CTO at Mass Mosaic and the CEO of Grokability, Inc. in San Diego, CA. Tweet at me @snipeyhead or read more...

  • Adam Culp

    Nicely written. Would be interested in hearing your expansion on feature branches in relation to pull requests. Or possibly a resource link.

    • Feature branches (for me anyway) are more of an artifact of working in dev teams for work. It’s probably less important overall in OSS, but for me it helps enforce the notion that each PR accomplishes one thing and only one thing. It can also help with letting me know what your PR is addressing. I get lots of PRs with no comment at all, so when the branch they’re opening the PR from on their fork is named something like “features/file-uploads”, it’s useful. Ultimately tho, as long as your PR addresses one individual fix or feature, I’m less picky about what you name your own branches.

  • Uncle Pickle

    A retro reflection on twigs with a bianary infusion might have been nice!

    • Super helpful, uncle Nick, thanks 😛