Contributing Guide Template

In this tutorial, you will learn about Contributing Guide Template. We cover key concepts, practical examples, and best practices to help you master this topic.

A contributing guide tells documentation contributors how to participate. Learn the essential sections every contributing guide needs and how to write one.

What You'll Learn

You will learn the essential sections of a contributing guide, how to write clear instructions for contributors, and how to maintain the guide as the project evolves.

Why It Matters

A good contributing guide lowers the barrier to entry. Contributors know exactly what to do, how to do it, and what standards to follow.

Real-World Use

DodaTech's contributing guide includes setup instructions, style requirements, PR Process, review expectations, and recognition policies.

flowchart LR
  A[Contributing Guide] --> B[Getting Started]
  A --> C[Workflow]
  A --> D[Standards]
  A --> E[Recognition]
  B --> F[Setup]
  B --> G[First Issue]
  C --> H[Branching]
  C --> I[PR Process]
  D --> J[Style Guide]
  D --> K[Quality Checklist]
  E --> L[Credits]
  E --> M[Maintainer Path]
  F:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Essential Sections

1. Welcome and Overview

Introduce the project and why contributions are valued.

# Contributing to DodaTech Tutorials

Thank you for considering contributing to DodaTech Tutorials.
Documentation contributions help thousands of developers learn
programming and security concepts.

This guide explains how to contribute effectively.

2. Getting Started

Step-by-step setup instructions.

## Setup

1. Fork the repository: https://github.com/dodatech/tutorials
2. Clone your fork:
   git clone https://github.com/YOUR-USERNAME/tutorials
   cd tutorials
3. Install dependencies:
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
4. Create a branch:
   git checkout -b my-contribution

3. Finding Work

How to find good first issues and what to work on.

# good-first-issues.yaml
where_to_find:
  - label: "good first issue"
    url: "https://github.com/dodatech/tutorials/labels/good%20first%20issue"
  - label: "help wanted"
    url: "https://github.com/dodatech/tutorials/labels/help%20wanted"

types_of_contributions:
  - Fix typos and grammar
  - Update outdated code examples
  - Add missing sections (Common Mistakes, FAQ)
  - Write new tutorials
  - Review existing pull requests

4. Style and Standards

Link to the style guide and quality checklist.

def validate_contribution(page_content):
    checks = []
    # Check required sections
    checks.append('What You Will Learn' in page_content)
    checks.append('Common Mistakes' in page_content)
    checks.append('FAQ' in page_content)
    checks.append('Mini Project' in page_content)
    
    # Check formatting
    checks.append('```' in page_content)  # code examples
    
    return all(checks), sum(1 for c in checks if not c)

missing_sections = validate_contribution("Some content")
print(f"All checks passed: {missing_sections[0]}")

Expected output:

All checks passed: False

5. Pull Request Process

## PR Process

1. Create a branch from `main`
2. Make your changes
3. Run the build locally: `python3 scripts/build.py --verify`
4. Commit with a descriptive message
5. Push and create a PR
6. Respond to reviewer feedback
7. PR is merged by a maintainer

6. Recognition

How contributors are recognized.

## Recognition

- All contributors are listed in CONTRIBUTORS.md
- Significant contributors are invited to become maintainers
- Quarterly contributor spotlight on the blog

Template Structure

# CONTRIBUTING.md template
sections:
  - title: Welcome
    required: true
    content: "Project description and appreciation"

  - title: Getting Started
    required: true
    content: "Setup instructions and prerequisites"

  - title: Finding Work
    required: true
    content: "Good first issues and contribution types"

  - title: Style Guide
    required: true
    content: "Link to style guide"

  - title: PR Process
    required: true
    content: "Step-by-step PR workflow"

  - title: Recognition
    required: false
    content: "How contributors are recognized"

Common Mistakes

1. Too Long

A contributing guide longer than the project README scares contributors. Keep it concise.

2. Outdated Instructions

Setup instructions that do not work frustrate contributors. Test them regularly.

3. No Style Guide Link

Contributors need to know formatting and voice standards. Link to the style guide.

4. Assuming Git Knowledge

Explain Git commands or link to a Git tutorial. Not all contributors are developers.

5. No Recognition Section

Contributors who feel unappreciated stop contributing. Recognize contributions publicly.

Practice Questions

1. What are the essential sections of a contributing guide?

Welcome, getting started, finding work, style and standards, PR process, and recognition.

2. Why should setup instructions be tested regularly?

Outdated instructions frustrate contributors and create unnecessary support requests.

3. How long should a contributing guide be?

Concise enough to read in 5-10 minutes. Link to detailed documents for advanced topics.

4. Why include a recognition section?

Contributors who feel valued continue contributing. Recognition encourages sustained participation.

5. Challenge: Write a contributing guide for an open source project of your choice. Include all essential sections.

FAQ

Mini Project

Create a contributing guide for a project. Include setup instructions, style requirements, PR process, and recognition policy. Test the setup instructions with a new contributor.

What's Next

Now that you can write a contributing guide, learn the PR Process for Docs. Then study Style Guide Adherence.