Contributing Guides: A Template
A template for writing your own contributing guide. Contributing guides are helpful documents that communicate how people can contribute to your open source project.
This template is meant to be a checklist to make sure you haven’t missed anything, rather than offering guidance on philosophy or approach. Your final guidelines may differ depending on your project and needs.
I made this template to share what I learned after reviewing 40 open source projects of all sizes and their contributing guides (or lack thereof). Thanks to all the examples used in this template:
Active Admin, Read The Docs, Mustache.js, Hoodie, Elasticsearch, Devise, Geocoder, Flask, Cucumber-ruby, Cookiecutter, Celery, Atom, Django, React, Requirejs, Node.js, Ember.js, Chef, Puppet, Travis CI, Express, Meteor, Angular, StandardIssueLabels
Special thanks also to @mikeal and his post "Healthy Open Source" about Node.js's contribution policies for inspiring this project.
How to get started
To use this template, create CONTRIBUTING.md in the top level of your project, copy the template, and fill it out with your information.
When you’re done, make sure people see your shiny new contributing guide:
- Link back to your contributing guide in your Readme. Create a section called “Contributing” and link to CONTRIBUTING.md: “Thanks for your interest in contributing! There are many ways to contribute to this project. Get started here (link).”
- If you have a website for your project, add a section called “Contributing” and link to your contributing guide. Or copy-paste your guide into the website and link to them in your CONTRIBUTING.md file.
Finally, a couple of tips to help you write:
- A friendly, welcoming voice will go a long way in making people feel excited to contribute to your project. Don’t forget to explain terms or concepts that might be confusing to a newcomer.
- Use this as an opportunity to lay the ground rules that will make you happy. The purpose of writing a guide is to make your life easier. It’s okay to say “XYZ pull requests are not accepted” or “I am busy, expect 1-2 weeks to review and merge your PR”. Clarifying your needs up front will make it much faster to review future contributions.
- Be concise. Adding too much detail might actually make people less likely to read your guide, which will defeat the purpose.
That’s it!
Contributing to this template
This template reflects what I learned from reviewing the policies of many open source projects, not my experience as an open source maintainer. If you think something important is missing or should be different based on your experience, I'd love to hear it! (Keep in mind this is meant to be a first pass checklist, not a full-fledged guide in itself.) If you have suggestions for improving this template, open an issue on this project.