Please see the source of this guide in the template repository.

About the Contributing Guide Template

Thank you for downloading this template from The Good Docs Project! Before using the template, read this template guide for information about how to complete each section. Want to explore more templates? Check them out in our templates GitLab repository.

Introduction

The contributing guide template provides a baseline for building your project's contributing guidelines and contribution workflow. This document will help you learn about contributing guides and how to use the template.

Why do you need a contributing guide?

Contributing guides are important because they communicate your process for contributing, which can help you with the following:

  • Attract additional help with your project.
  • Ensure the quality of work that your contributors submit.
  • Make your project more inclusive because the contributing guide allows people to onboard themselves without assistance.

You can tailor your contributing guide to focus on one or a variety of contribution types, such as the following:

  • Source code
  • Documentation
  • Outreach initiatives
  • Translation efforts
  • Issue management
  • Content strategy
  • IT support
  • Social media

What you include in your contributing guide depends on your project's needs.

When do you need a contributing guide?

Regardless of how big, small, new, or old your project is, you will need a contributing guide for the following reasons:

  • Your project is open source and relies on outside collaboration.
  • To attract more contributors to your project.
  • To enhance the quality of the contributions.
  • To establish processes, expectations, and guidelines for contributing.
  • To ensure that contributors have all the information and resources available to contribute; this gives your contributors a way to self-serve and help themselves, which reduces some of the maintenance burdens on the project maintainers.

Voice and tone

Before you build your contributing guide, consider what kind of tone and voice you want to communicate to contributors. The "voice" communicates your personality, while the "tone" communicates your attitude. Ask yourself if you want your contributing guide to sound formal, humorous, or conversational.

The following are some examples:

  • Conversational tone and voice: We're excited to have you join the project! Now that you've joined, check out the following ways you can contribute.
  • Formal tone and voice: Thank you for your interest in joining the project. The following are ways you can contribute.

Best practices

Open source projects name this file in all caps to make it easier to discover: CONTRIBUTING.md.

Template overview

Throughout the contributing guide template, you will see the following:

  • A variety of sections and subsections to help you provide granularity.
  • Boilerplate text that you can change.
    Note: Boilerplate is the standardized text you can use and reuse within the template.
  • Placeholder text indicated in {curly brackets}.

The contributing guide template is customizable; you can reorder, rename, and remove sections that do not apply to your project.

The following sections provide guidance and context on how to fill out the contributing guide template.

About the "Welcome" section

Introduce your project to your contributors with a welcome message. In your welcome message, list and explain how people can contribute and refer them to those sections within your contributing guide. Also, list contributions your project does not accept to clarify the scope.

Example: Welcome to the Open Source Project's contributing guide, and thank you for your interest.

If you would like to contribute to a specific part of the project, check out the following list of contributions that we accept and their corresponding sections that are within this guide:

  • To contribute to our templates, see the following:

    • Templates Contributing Process
    • Our Content Style Guide
    • Criteria for the Templates Submissions and Reviews

  • To contribute to our content strategy, see the following:

    • Content Strategy Contributing Process
    • Share Your Content Strategy Ideas
    • Content Strategy Workshops

  • To contribute to our style guide, see the following:

    • Style Guide Contributing Process
    • Our Content Style Guide
    • Share Your Content Style Ideas

However, at this time, we do not accept the following contributions:

  • Source code
  • Project maintenance
  • Translation
  • Issue triaging

About the "Overview" section

Provide a brief description of your project's purpose and objectives that you want to highlight to contributors.

Example: The purpose of The Open Source Project is to unify software developers who can collaborate to produce a high-quality analytics application for data scientists.

About the "Ground rules" section

Inform your contributors about your project's behavior policies. Behavior policies are rules and expectations on how to behave and not behave when contributing.

Provide a list of general behavior policies or share a link to your Code of Conduct if you have one established.

Example: Before contributing, read our Code of Conduct to learn more about our collection of rules, standards, values, and behavior expectations that you must adhere to.

Example: To be an active contributor, you must adhere to the following behavior policies:

  • Be respectful of differing viewpoints.
  • Kindly accept constructive criticism.
  • Do not use derogatory language.
  • Be empathetic towards fellow contributors.

About the "Community engagement" section

Provide information on how contributors can engage with your project outside of their contributions; this can include sharing recurring meeting details, a link to your project's Slack space, an email distribution group, or a link that allows contributors to sign up for newsletters.

About the "Share ideas" section

Describe how contributors can propose their ideas for the project. Ideas can be suggestions for process improvements, new tools to use, new documentation, and more. Ensure you mention where and how contributors can share their ideas and the review and approval process. Alternatively, you can share a link to a template or form that contributors can use to share their ideas.

About the "Before you start" section

List and describe contributors' prerequisites before contributing to the project. A prerequisite is any condition that must happen before a person can contribute.

Example: Before you start contributing, ensure you have the following:

About the "Environment setup" section

An environment is a workspace on your computer that contains a set of necessary programming tools, applications, and plugins to develop source code. This section is mainly relevant for people interested in contributing to your project's source code.

Provide a procedure on how to set up the environment for your project. As you explain how to set up the environment, ensure you provide any conditional steps, especially if there are different steps for specific operating systems.

About the "Troubleshoot" section

Describe or provide an external link to a procedure to diagnose and resolve problems that may arise when contributors set up their environment. The primary purpose of this section is to help contributors understand why there is a problem and how they can fix it.

About the "Best practices" section

List and describe best practices for contributing to your project; sharing best practices can ensure the quality of contributions. Best practices can include coding, managing local and remote repositories, and other general standards you believe would benefit contributors to follow for your project.

For inspiration on best practices, specifically for coding, see the following articles:

Also, if you have a parent guide for best practices, provide a link to it in this section instead of listing all the best practices from the parent guide.

About the "Content style guide" section

A style guide contains a set of standards on how to write and format content consistently. If you accept documentation contributions and have established a style guide, explain the purpose of a style guide and share an external link to it for contributors to review and reference. However, if your project does not have a content style guide but would like to establish one, use The Good Docs Project's Style Guide template as a baseline for creating one.

Example: Read our Style Guide to understand our guidelines for formatting and writing documents. The purpose of our style guide is to ensure consistency in the tone, voice, and structure of our documentation.

About the "Contribution workflow" section

This section contains the following subsections to help describe your project's contribution workflow:

  • Fork and clone repositories: Identify repositories that contributors must fork and clone for your project. Also, since the process to fork and clone repositories is the same for most version control tools, such as GitHub and GitLab, feel free to link contributors to read the Using the Fork-and-Branch Git Workflow article by Scott Lowe or to any Git guide.

  • Report issues and bugs: Explain how contributors can report problems with the User Interface (UI), application, source code, and more.

  • Commit messages: Explain how contributors can create and format commit messages. Feel free to link contributors to read How to Write Better Git Commit Messages - A Step-By-Step Guide by freeCodeCamp; this article provides examples of both good and bad commit messages.

  • Branch creation: Explain how contributors can create branches and merge changes.

  • Pull requests: Explain how contributors can submit pull requests (PRs). You should ensure that you address the following:

    • Your project's PR merge policies
    • Who reviews PRs
    • The estimated timeframe for PR reviews
    • What can a contributor do if they do not receive a response
    • What a contributor can do to get their PR reviewed
    • The approval and review process

  • Releases: Explain your project's release process and cadence, such as if they are monthly, bimonthly, weekly, or continuous.

  • Issue management: Explain the general process for how your project manages issues, such as tagging and assigning issues.

  • Text formats: Explain what text formats contributors must use; this is especially important for documentation contributions. Text format types include a specific Markdown flavor, HTML, and JSON.

Additional resources

Explore other templates from The Good Docs Project. Use our feedback form to give feedback on this template.