Setting Guidelines for Contributors
Table of contents
Guidelines are created to communicate how a person should contribute to a project.
About contributing guidelines
For the repository owner, contribution guidelines are a way to communicate how people should contribute. For contributors, it helps them verify that they are submitting well-formed pull requests and opening useful issues.
Adding a CONTRIBUTING file
You can add the contribution guidelines file in the folder you want to communicate to the contributors. This file would include:
Steps for creating issues or pull requests.
Links to external documentation or code of conduct.
Examples of contribution guidelines
How To Make a Contributing Guide, by CNC
This section is for the project maintainers or the technical writers who need a Contributing Guide for their project. The goal of a CONTRIBUTING.md file is to increase the number of successful contributors to your project.
Below are the sections that you can include in your CONTRIBUTING.md file or create separate .md files for each section. You can also find a template of this CONTRIBUTING.md template of the CNCF project-template repository.
Introduction
Contributing guide is the first place that new contributors seek to understand the project and whether the project welcomes contributors or not. It must include content for new contributors and developer documentation as well(or links to them incase they are large in size). This would make it easy for everyone to find the developer documentation without having to search for it.
Ways to Contribute
Maintainers do more than just programming and technical decision-making. There are multiple functions and roles on a project like marketing, content creation, technical writing, etc. If you would accept help with any of these tasks, call that out to attract a more diverse set of contributors with a complimentary skillet to your existing contributors.
Find an Issue
Often contributors want to help but don't know where to start. If you have an issue labeling strategy, explain it in this file. Let contributors know how they should indicate that they want to work on an issue, for example, "I would like to work on this".
Ask for help
Expect that all contributors will get stuck sometimes and figure out how they should ask for help. This is a great time to not only direct them to the proper communication channel but also provide links to relevant documentation such as a contributing tutorial, troubleshooting guides, etc.
Pull Request Lifecycle
Add the structure/workflow of your pull requests process. This would define a basic structure for the contributors and reviewers.
Development Environment Setup
Provide enough information so that someone can find your project on the weekend and get set up, build the code, test it, and submit a pull request successfully without having to ask any questions.
You should explain how to do at least these basic tasks:
Get the source code.
Retrieve any dependencies.
Build the source code.
Run the project locally.
Test the source code, unit, and 'integration' or 'end-to-end'.
Generate and preview the documentation locally.
Sign Your Commits
Many new contributors do not have experience with having to sign or agree to a DCO or CLA. Depending on which your project uses, keep either the text for the DCO or CLA sections.
Pull Request Checklist
Give the contributors an idea of how their pull requests are evaluated and how to run those checks locally before submitting the pull request. Document the checklist in the CONTRIBUTING.md file but also in the GitHub Pull Request Template.