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.
Open an issue or draft PR to walk them through your idea
Sometimes the maintainer won’t want whatever your feature or improvement is – and there’s not a lot you can do about that – but talking through the idea, and how you plan on approaching it will improve your chances of getting your changes merged. Provide a clear use-case, how your solution will solve the problem, and how you plan on approaching the issue from a technical and architectural perspective. Sometimes they’ll outright reject it – but a lot of times, if you can show them the direction you’re thinking, they’ll try to help you get to a place where your PR will be merged. If it’s a good feature with a good use case and it won’t screw up other users with different use-cases, that’s a pretty compelling reason to want to accept a PR.
Also discuss how it can be tested, not just now, but moving forward, and in an automated way. If I get the feeling you’re dropping something in my lap because you want it but I won’t have an easy/cheap way to automatically build it or test it as part of the CI process, I’m going to be less excited. I might still merge it, but with the caveat that it’s kinda on you to keep it working as the project and ecosystems evolve.
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.
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.)
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.
Each PR should fix exactly one bug, or add exactly one feature.
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.
