Thinking about contributing to an open source project?

There's this open source project you've been reading about. For some reason, it seems really interesting and you'd like to be part of it. What better way to achieve this than getting your hands dirty and submitting some pull requests?

Just hold on a second! Before you start, here's a list of criteria that I consider essential when deciding whether to contribute to a particular open source project or not:

  • readme/docs with clear steps on how to get started
  • development environment that's easy to get up and running (docker, vagrant, script, something)
  • tests that are quick to run - unit/integration tests separated from live tests
  • tight feedback loop when developing - e.g. no need to rely on the GitHub integrated CI while developing
  • timely reviews

The lack of any of these will make your experience unpleasant - I promise! - and there are great chances that you'll give up and move on to the next project, so it's better to try to avoid this altogether.


Now let me explain, since there might also be project maintainers reading this.

It's all about convenience and avoiding frustration. Generally, people take on contributing to some open source project because they want to learn more about a particular technology and/or they have some free time and want to try out something new. [That is unless they are forced to do so because of some requirement in their project at work or whatnot - but these situations are not relevant now.]

Either because of a new technology being involved or because the potential contributor doesn't have too much time on their hands, there is a short time frame in which the project can win them over or not.

You don't want people spending that time figuring out how to set up the dev dependencies, how to run tests, and discover that they need some credentials for whatever reason. Or while trying to understand how some modules are tied together, having to wait ten minutes (actually.. any amount of minutes) for a test run on every change they make.

Finally, if they succeeded submitting a pull request (which is a great thing, it means they didn't get lost on the way) - you don't want to reply with review comments a week later. By that time, maybe your potential contributor has found a new technology/project to take a look at or maybe they just don't have the free time anymore.


That's how I feel. Of course, these criteria apply to the average, unbiased contributor. Fortunately, there are also people who will observe that a project might be lacking in one of the mentioned aspects and they will jump in to help with that; but I think that's all based on luck!

So if you're someone looking to contribute to a project, I suggest you try out this checklist! It should save you time and frustration. Similarly, if you're a project maintainer, try to always think about how you can make your project more approachable to new contributors.

Happy hacking!

Mihnea Dobrescu-Balaur

Building @Hootsuite Analytics. Interested in Open Source, programming languages and the Open Web. Big fan of basketball and photography. Tweet @mihneadb.

Bucharest, Romania

Subscribe to Mihnea DB

Get the latest posts delivered right to your inbox.

or subscribe via RSS with Feedly!