(Photo by Zulian Firmansyah on Unsplash)
I recently became concerned about risks from frontier AI models, so I committed to contributing to Inspect AI to make AI safer over a 30-day period. I’ve worked on other open-source projects before, but I needed to know how things worked on Inspect so I could make meaningful contributions without duplicating effort. After searching for process documentation and finding none, I combed through issues and pull requests (PRs) to learn what others were doing, what types of PRs were getting accepted, and what I’d need to do to help. Of course, with this approach, there was no guarantee that I learned the right takeaways – I may have picked up practices that the maintainers were OK with but weren’t ideal.
I noticed that other people sometimes just created a new issue with their question, like “how do I build the docs?” and realized that everyone has these questions. If they’re not asking, they’re just digging in to figure it out on their own like I did, wasting time they could be actually contributing.
Contributor time is precious – people are volunteering their time and expertise, so it should be as easy as possible for them to make meaningful contributions to the project right away. They shouldn’t need to figure out how to build and test or claim an issue to work on.
The solution to this problem is simple: Create a CONTRIBUTING.md file in the root of your repository, and make sure it answers the questions everyone will have:
- How do I report a bug?
- What’s a good first issue to start working on?
- After I choose an issue I’d like to fix, what happens next? I don’t want to work on something for a few days, only to see someone else create a pull request (PR) before I do, rendering my work meaningless.
- How do I build and test locally?
- Before I create a PR, what should I check or do? Do I need to install the pre-commit hooks? Lint, format, run tests?
- Are there code formatting guidelines? Does the formatter handle all of them, or are there some I’ll need to look out for and do manually?
- Do I need to do anything besides formatting and getting unit tests to pass? Does new code always need to be covered by unit tests?
When you create a contributing guide with this exact filename in your repository root, GitHub will show it in two additional places so it’s easier for people to find – in a Contributing tab on the repository overview (next to the README tab) and as a link in the About section in the repository sidebar.
I did this for Inspect, so now its contributing guide answers the questions I had – and the ones I saw other people asking in issues. Now those questions are documented up front so nobody needs to ask.
This solves a few problems for contributors as well as maintainers:
- contributors don’t need to waste time asking basic questions
- maintainers don’t need to waste time answering basic questions
- expectations for contributors are clear so PRs are better (less repeating yourself about how unit tests are needed, please run the formatter, etc)
And most importantly, people don’t just leave because they don’t know how to help, don’t know how to build and test, or don’t know how to report an issue. They have everything they need right up front so it’s easy for them to contribute their first bug report, documentation, bug fix, or feature.
If your project doesn’t have a solid CONTRIBUTING.md yet, you’re losing contributors right now. Spend an hour writing one, and your future contributors and future self will thank you.