Michael JolleyIt seems that lately I’ve been creating a new public repo every other day. A few have even received pull requests from other contributors. As that list of contributors began to grow I realized there were a few things that I, and probably other repository maintainers, want to provide. So, as always, when I learn something new, I write a blog post.
My goal is to explain the benefits of acknowledging contributors and providing them with contributing and code of conduct guidelines.
Contributing Guidelines
For the most part, contributors have seen my repositories on our Twitch stream and wanted to help. The benefit to the stream is that viewers can see the process we use to submit pull requests, our branching strategies, etc. However, for those that want to join in on the fun later, it’s likely that their pull requests will be directed to the wrong branch or perhaps for an issue that is already in progress by another contributor.
To help, I went on a search for example CONTRIBUTING.md files across GitHub. There were several great examples. A few are:
I modified thoughtbot’s Factory Bot Rails version to meet my needs and added it to all my active public repositories. You can see an example in our Aviary repo.
At a minimum, your CONTRIBUTING.md should include details about:
- What type of contributions are permitted? (documentation/code/ideas/tests/examples/etc.)
- Instructions for adding issues
- Instructions for forking & submitting pull requests
This basic information gives potential contributors a little more confidence about submitting that pull request by alleviating the fear they’ll be blasted for using the wrong base branch.
Code of Conduct
I’ll admit I’m a little knew to this one. I’m not sure I’ve ever read a repositories Code of Conduct before this week. It’s easy to overlook when you expect the best from people and/or haven’t experienced the effects of poor conduct when participating in public repo communities. But the fact that I’ve never personally experienced something doesn’t mean I should overlook that bad behavior in the development community does exist. In fact, regardless of my personal experiences, I want everyone to feel included and safe to share ideas and collaborate.
Having a CODE_OF_CONDUCT.md in your public repository lets potential contributors know in advance how they can expect to be treated by the community and maintainers. Contributor Covenant is a great resource for a Code of Conduct for your repository.
Acknowledging Contributions
I love new contributors! It makes my day when I get a notification that someone created an issue, submitted a pull request or even just forked the repository. There are several ways to show love for your contributors but one I’ve recently implemented (and love) is the All Contributors specification.
When someone contributes I simply comment on an issue or pull request and the All Contributors bot creates a pull request that gives that person an acknowledgement on our README.md.
An example from our VS Code extension is:
Not all contributions are code. Using All Contributors, I can recognize contributors for everything from ideas, questions, documentation, tests, examples and more. A full listing of options is available on their emoji key.
It’s a fun way to give credit where it’s due and encourage others to participate.
Wrap it up Mike
That’s my TED Talk for today. Do you have ideas on how to help new contributors join in? Let me hear them!
