This is a learning activity whose objective is to show you what to include in a CONTRIBUTING.md and how to build and maintain your file in an open-source project.

The activity is for you if you have an open science project or are a Mozilla Study Group lead seeking to appeal to and grow a community of contributors around your project.

You will need a collaborative document editor such as Google Docs, and a Markdown viewer to test your file.

If you are planning to have people participate by adding content to your software, then you must have a CONTRIBUTING.md. These files also referred to as the contributing guidelines, or software contribution guidelines, are text files included in free and open-source packages or other open media software by the project owner or manager. The file describes how anyone can take part in the project by performing certain tasks such as code formatting, test fixes, or even making patch submissions.

Other than providing a guide on how to participate, the presence of this file should increase your project’s chances of receiving crowdsourced contributions and so should not be ignored if the success of your project is dependent on user contributions.

 Who is the CONTRIBUTING.md file meant for

This file is useful to three groups of people. First, you, the person seeking contributions and therefore best placed to create and maintain the CONTRIBUTING.md. The file will help you outline how you expect others to contribute to the project.

The next beneficiaries are contributors, people who are interested in knowing what items they are welcome to tackle and how they can navigate the project.

The third group that the CONTRIBUTING.MD addresses are the project consumers. These are users who want to utilize the project offering to work on or build their projects.

Where should the CONTRIBUTING.md be located?

CONTRIBUTING.md should be placed in your root directory, along with README.md and LICENSE.md. If you haven’t already defined possible mechanisms of contribution, consider creating a draft CONTRIBUTING.md file with a “coming up soon message” informing potential contributors of your intention to solicit their input. Include the project lead’s contact information for follow-up. 

The CONTRIBUTING.md will be accessed from your project. It is important therefore to have a clean, orderly, and welcoming project structure, such as this example. 

What to include in the CONTRIBUTING.md file

You can begin by creating an offline draft file, or by using a Markdown editor such as Dillinger to practice building your online CONTRIBUTING file before posting it online.

Generate CONTRIBUTING.MD

Consider including the following components in your CONTRIBUTING.md file.

  1. A welcome note

Let contributors know you are keen to have them on board and look forward to working with them.

  1. Table of Contents 

To make it easy for contributors to jump to sections of their interests, consider having a table of contents. Each heading should have its URL link. To do this in Markdown, use [] and follow with the header in parenthesis in the format: [Header name] (#header name) 

  1. Provide Links 

Include links for directions to where different items are located in your project and to resources that could be useful to contributors, such as:

  • Links to resources: such as important documents, bugs, and communication pages
  • Templates: Templates offer a structured format that makes it easier for the user to record detailed information and for the project manager to quickly analyse the information. Include hyperlinks to your templates, such as the bug reporting and enhancement suggestion templates. Make it easy for users to use your templates offline by having them downloadable.
  • Test location:  link to where tests are situated in your directories.
  •  Submit changes link: To direct users on how they can make and submit changes. Include information on what kind of responses they are likely to get, and how long they are likely to wait for a response.
  • Development environment details: This directs users on how to set up their development environment. If the details already exist in the README.md, include a link in the CONTRIBUTING.md as well.
  1. Include “How To” details

Make it easy for users to contribute by giving directions on how to navigate your project in the form of “How to” instructions. Consider including the following:

  • How to make a bug report: Direct users on how to report issues in the project. Make the process as simple as possible, anticipating challenges and providing links/hyperlinks to solutions. Unclutter the section by providing links that respond to concerns such as a list of bugs already reported so that users can check if what they want to report has been reported on earlier, a step-by-step “how to”, “bug trackers”, “FAQs “, links/hyperlinks and any other that will assist users in making a bug report. 
  • How to fix a bug: some users may want to fix a bug, in addition to reporting on it. It can be helpful to give some guidelines on the types of bugs that users are allowed to fix, and style guides with examples for different scripts, issues, and pull request labels.
  • How to suggest enhancements: In this section, provide a guide on how users can submit enhancement suggestions. Such suggestions may include new features or improvements to functionality. Offer users a link/hyperlink to guidelines, that will help you as the maintainer and the community understand their suggestions. 

Include a link/hyperlink to related suggestions, debugging guide, and the latest version of your project that the users can access to see if the enhancement they intend to suggest has already been addressed or implemented in other ways. Encourage users to be as detailed as possible on their suggestions and offer a link to an enhancement suggestion template to get structured and detailed suggestions. Encourage them to test if their enhancement gets the desired behavior by providing access to the project config settings

  • Coding conventions and Style guide: For GIT commit messages, let the user know what tense, mood, number of characters, and other stylistic formats to use in the project. For example, you can instruct users to use present tense only, restrict the number of characters on the first line, or even whether emojis are allowed, and how to include them. Address how to reference issues, pull requests, and how to include certain codes in this section of the CONTRIBUTING.md.

Give code examples using different scripts such as JavaScript, Documentation, Coffee Script, or Specs style guides to guide the user in the coding conventions that you are using in the project.

  1. Other Components

These are components that address housekeeping and your responsibilities as far as interactions in the project are concerned. Aim at making users feel comfortable working with you. Consider including:

  • Code of Conduct – You may want to make this part of your CONTRIBUTING.md to set the tone for contributions. The code of conduct can also be a separate Markdown file linked in the CONTRIBUTING.md or the LICENSE.md.
  • Recognition section– Create a “thank you” section for contributors listing any recognition that they might receive for their input in your project.
  • Project owner and contributors information: Make the project have a human touch by listing the core contributors, how to contact them, or link to a humans.txt file in your root directory which lets people know who they are working with, that is, humans, not bots.
  • Where can I get help? – an extension that has links to reliable communication channels that respond to questions can be a useful inclusion as it shows you are interested in the challenges that the user may be facing with your project and offers you an opportunity to review your work from the users’ point of view.

Reference Files

CONTRIBUTING.md will often reference the LICENSE.md., the README.md, and a human.txt file. You must create all the files you reference in your root directory.

To help you create the LICENSE.md, use follow the link https://creativecommons.org/choose/   or   https://license.md/, incorporate relevant text.

The README.md contains a description and set-up and installation details of your project that you may want to reference in your CONTRIBUTING.md. To create a README.md, you can follow the instructions here.

Use the humans.txt file to recognize the contributors. Once the file is deployed, it will be accessible through the link provided on your CONTRIBUTING.md file or your project structure. If you need assistance to create a humans.txt file, follow this example.  Remember to be polite and thank people promptly for their contributions, issues, and requests, as this will keep interactions open, and improve the quality of contribution.

You can also create unique ids, known as Digital Object Identifiers, (DOIs) to make your data sets easier to cite in academic literature. Data archiving tools such as Zenodo can assign DOI and issue an archive for a GitHub.com repository.