Get Others Involved in Your Project with a CONTRIBUTING Guide

I recently shared a README Template and strategies for improving your project's README. The README's purpose is to introduce new users to your project and help them start using it.

Today we're going to take a look at another helpful introductory document: the CONTRIBUTING guide.

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 master?
  • 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 CONTRIBUTING guidelines.

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 .md extension.

Contributing-guidelines.jpg

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.

Familiarize yourself with basic Markdown syntax to properly format your document. Add links to other documents and include images.

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.

Introduction

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!

Important Resources

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 CONTRIBUTING guide.

Possibilities include:

  • 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.

Processes

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 CONTRIBUTING guide:

  • 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

Contributing Code

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 master the latest?
    • Is there a stable or develop branch?
  • 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 CONTRIBUTING Guide!

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:

Further Reading: