A Practical Guide to Growing Your Open Source Project: Part 1 – Contributors

This post originally appeared in my free daily newsletter on startups and engineering.
You can join 200+ subscribers here: https://matt-rickard.com/subscribe/

Open-source is great for engineers. It allows us to share our work and collaborate with people from around the world. But what if nobody else shows up?

Getting traction and growing an open-source project is really, really difficult. I know because I've spent the last few years doing that. I've been an open-source maintainer of minikube (21k stars), skaffold (11.5k stars), kubeflow (10.6k stars), distroless (10.2k stars), and active within the Kubernetes (79k stars) and Docker (60k stars) communities.

I'm going to tell you practical tips that you can use today to bring on more contributors, more users, and to develop a more vibrant community for your open-source project.

These tips are based on my own experience growing open source projects – things that I did that worked, or mistakes I made.

Part one is about growing the contributor base.

1. Make it dead easy to contribute.

We have a cognitive bias that we like things more if we feel like we had a part in building them (read: The IKEA Effect in Software Development). Despite this cognitive bias, most projects unwillingly make it difficult for outside contributors. Contributor onboarding can't be an afterthought. Here's how to make contributing to your project dead easy.

• The build script should be one-step and with minimal dependencies. Complex toolchains and environment dependencies mean friction. For skaffold, the build process was entirely dockerized – new contributors didn't have to spend time setting up their environment. No more of "but it worked on my machine".
• The test script should be one-step and be as close as possible to what runs in CI. When the tests pass locally, but CI runs something entirely different, contributors churn. Make sure that the test command is easy to run, something like make test or ./test.sh, and that it runs all the unit, integration, and linting tasks.
• Reduce flakes, or false negatives, in CI. The worst feeling is when a contributor painstakingly checks that their code conforms to the project's standards and tests, only to see CI fail miserably. How do they debug that? Nobody wants to debug someone else's CI system.
• Accept contributions, even if you have to fix them up later. Onboarding contributors is an exercise in mentorship. You'll have to dedicate time upfront as these users learn the codebase and project style. This takes time. Sometimes, features need to get merged before a pull request can be fully iterated. Pull requests that are open too long become difficult to merge – my law of pull requests – "The longer a pull request has been open, the longer it will take to merge."
• Use the "Good First Issue" tag. GitHub actually treats these as special issues, pushing them onto the GitHub feed for higher visibility. Use that to your advantage and craft well-written issues tagged as "good-first-issue". They can be as simple as backlogged bug fixes. But you have to already know how to fix the issue and it has to be contained to a small testable surface, there's a low probability that new contributors will be able to fix deep problems in your project across hundreds of files.
• Advanced tip: have a way for approved contributors to re-trigger CI. For example, Kubernetes, Kubeflow, and minikube use a tool called prow to run tests. Prow comes with a prow-bot that can accept different commands, automatically tagging issues or rerunning specific tests. Not for small projects, but this can alleviate maintainer headaches caused by trivial busy work.
• Advanced tip: previews using Netlify or Vercel. Especially for documentation and web applications, have previews autogenerated on pull requests. Even if contributors have gone through all the steps, it's great for them and the maintainers to visualize the changes while reviewing. This is great for non-technical contributions, such as verifying documentation changes.

Tomorrow, in Part 2, I'll cover how to build a community for your open source project. Then, on Wednesday, Part 3 will cover the top of the funnel with potential users. If you haven't already, make sure you subscribe so you don't miss new posts every day.