Today we're going to take a look at another helpful introductory document: the
Every software project comes with its own particular development process, expectations, and rules. These processes and requirements differ widely among development teams. There many questions that can be answered differently for each project:
- What information is needed when filing a new issue?
- How can I get the log files?
- Do you want people to file an issue before attempting a fix?
- Are pull requests without corresponding issues acceptable?
- How should new tests be added?
- What are the requirements for accepting changes into
- Are there any coding standards I need to follow?
- What is the Pull Request review process?
Team leaders and project maintainers can use the
CONTRIBUTING guide to communicate rules and processes for contributing to the project. Since the process and expectations are documented, contributors can verify ahead of time that they are submitting changes and issues properly. Also, because the guidelines are clearly defined, improper issues or pull requests can be quickly rejected with a reference to the
Benefits When Using GitHub
GitHub has built-in support for
CONTRIBUTING files. Whenever someone opens a pull request or creates a new issue, a banner will be included with a link to your guidelines.
Make sure that your
CONTRIBUTING file is located in your repository root,
docs folder, or
.github folder. GitHub supports
CONTRIBUTING files with no extension, a
.txt extension, or a
It's Never Too Early!
Often new projects will skip the documentation steps because they "don't need it yet." However, others can't contribute to your great project if you don't provide the resources to get them started.
In the early stages of a project, a simple
CONTRIBUTING guide will probably suffice. You probably don't need strict processes yet. That's ok! Simply start with the basics and document your development setup and tell others what kind of contributions you are seeking. Over time your
CONTRIBUTING guide should evolve to address problem areas, commonly asked questions, and new processes.
A Note About Formatting
Just like I said about your
README, if your
CONTRIBUTING guide is disorganized and poorly formatted, nobody is going to give it the time of day.
Most readers in our present era will be viewing your
CONTRIBUTING guide in their web browser. Organizing your
CONTRIBUTING guide into well-organized sections, formatting text so it stands out, and including a table of contents should be a priority.
Elements of a Good Contributing Guide
Contributing guides vary in their coverage and length. The actual material is greatly dependent on the details of your particular project, the kind of contributions you are seeking, and the processes that your team wants to use.
Instead of covering specifics, let's take a look at some essential elements that a good contributing guide covers. Afterward I'll provide links to
CONTRIBUTING files from around the web.
It's always nice to start by welcoming interested contributors to your project. Thank them for considering your project and tell them that you are excited for their contributions.
The introduction is a good place to cover what kinds of contributions you are seeking. You don't have to waste anybody's time if there is a mismatch of interests.
You can also cover your roadmap, who is on the team, and how people can get in touch with you.
Table of Contents
A short document can likely get away without a table of contents, but providing one will make your document much more accessible to your contributors. Instead of scrolling to find the details they are searching for, they can just click on the relevant anchor link. If you are using Markdown, you can create anchor links to your headers:
## Table of Contents 1. [About the Project](#about-the-project) 1. [Project Status](#project-status) 1. [Getting Started](#getting-started) # About the Project ## Project Status # Getting Started
Code of Conduct
The internet can be a harsh place, so at some point you will want to decide on a code of conduct. If it's simple, you can include it directly in your contributing guide. If you have a separate
CODE_OF_CONDUCT file, you should link to it here.
Protect your project by laying down good behavioral rules up front!
There are likely other resources that are available to people interested in contributing to your project. Make sure to include relevant instructions and links in your
- API documentation
- Other reference documents
- Useful blog posts
- Your issue tracker
- Google group information
- Slack channel
- Email list
Also make sure that you tell people how they can ask questions or get help with your project.
All teams have processes, and you should document yours so contributors have a reference.
By documenting your processes, you provide contributors with helpful references to get started on your project. You also protect your own time, as you can reject or close items that do not comply with the project guidelines.
Try to cover the following common processes in your
- How to get questions answered
- How to request new features or enhancements
- How to help improve documentation
- How to report a bug
- Describe information should be included and how can they find it
- Submitting pull requests
- How code will be reviewed/approved
- How feedback is expected to be addressed
- Expected response timeframes
- Include links to high-quality bug reports or pull requests for other users to reference
The meat of your guide should describe how other developers can start working on your project. You should provide all relevant details that someone would need to know in order to start working on your project.
Cover topics such as:
- How to set up the development environment
- How to find issues to work on
- What is the development process for your project?
- Is there a
- How to build the project
- How to add new modules or files to the build
- How to test the project
- Where to find tests
- How to add new tests
- Relevant style guidelines or code formatting rules
Link to Your
Make sure to link to your
CONTRIBUTING file from your
README so more people see it. Remember: if you place the
CONTRIBUTING file in your project’s repository, GitHub will automatically link to your file when a contributor creates an issue or opens a pull request.
Example Contributing Guides
Here are some high quality
CONTRIBUTING guides to use as a reference:
- Atom CONTRIBUTING.md
- Open Government CONTRIBUTING.md
- Rails CONTRIBUTING.md
- Angular.js CONTRIBUTING.md
- OpenOpps Platform CONTRIBUTING.md
- Nayafia's CONTRIBUTING Template
- PurpleBooth's Contributing Template