To help your project contributors do good work, you can add a file with contribution guidelines to the root of your project's repository. Then, whenever someone opens a pull request or creates an issue, they will see a link to that file.

contributing-guidelines

For the repository owner, contribution guidelines are a way to quickly communicate how people should contribute.

For contributors, these guidelines help them verify that they're submitting well-formed pull requests and opening useful issues.

For both owners and contributors, contribution guidelines save time and hassle generated by improperly created pull requests or issues that have to be rejected and re-submitted.

Tip: Repository maintainers can set specific guidelines for issues by creating an issue template or pull request template for a repository.

Adding a CONTRIBUTING file

  1. On GitHub, navigate to the main page of the repository.

  2. Above the file list, click Create new file. The New file button

  3. Decide whether to store your contributing guidelines in the repository's root or in a hidden directory called .github. Then, in the file name field, type the name and extension for the file. Contributing guidelines filenames are not case sensitive, and can have an extension such as .md or .txt. New file name

    • To make your contributing guidelines visible in the repository's root directory, type CONTRIBUTING.
    • To store your file in a hidden directory, type .github/ to create the new directory, then CONTRIBUTING.
  4. In the new file, add contribution guidelines. These could include:

    • Steps for creating good issues or pull requests.
    • Links to external documentation, mailing lists, or a code of conduct.
    • Community and behavioral expectations.
  5. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file. Commit message for your change

  6. Below the commit message fields, decide whether to add your commit to the current branch or to a new branch. If your current branch is master, you should choose to create a new branch for your commit and then create a pull request. Commit branch options

  7. Click Propose new file. Commit new file button

Examples of contribution guidelines

If you're stumped, here are some good examples of contribution guidelines:

Further reading