Blog
5 min read

How to Write a CONTRIBUTING.md

A practical guide to writing CONTRIBUTING.md files that attract and guide open-source contributors. Includes templates and real examples.

A CONTRIBUTING.md file tells potential contributors how to help your project. Without one, most developers won't even attempt to contribute — they don't know where to start.

Why it matters

GitHub highlights the CONTRIBUTING.md file in several places:

  • When someone opens a new issue, GitHub links to it
  • When someone creates a pull request, GitHub links to it
  • It appears in the "Community" tab of your repository

This visibility means your contributing guide is a high-traffic document. Make it count.

Essential sections

Welcome message

Start with a warm welcome. People are about to donate their time:

markdown
# Contributing to ProjectName

Thank you for considering contributing to ProjectName!
Every contribution helps, whether it's fixing a typo, reporting
a bug, or implementing a new feature.

Getting started

Provide exact steps from zero to running:

markdown
## Getting Started

### Prerequisites

- Node.js 20+
- pnpm 9+
- PostgreSQL 16

### Setup

1. Fork and clone the repository:
   \`\`\`bash
   git clone https://github.com/YOUR_USERNAME/project.git
   cd project
   \`\`\`

2. Install dependencies:
   \`\`\`bash
   pnpm install
   \`\`\`

3. Copy the environment file:
   \`\`\`bash
   cp .env.example .env
   \`\`\`

4. Start the development server:
   \`\`\`bash
   pnpm dev
   \`\`\`

Finding work

Help contributors find appropriate tasks:

markdown
## Finding Something to Work On

- **Good first issues:** [Browse here](https://github.com/owner/repo/labels/good%20first%20issue)
- **Help wanted:** [Browse here](https://github.com/owner/repo/labels/help%20wanted)
- **Bug reports:** Check the issues list for confirmed bugs

If you want to work on something not in the issue tracker,
open an issue first to discuss the approach.

Making changes

Define your workflow:

markdown
## Making Changes

1. Create a new branch from `main`:
   \`\`\`bash
   git checkout -b feature/your-feature-name
   \`\`\`

2. Make your changes. Write tests for new functionality.

3. Run the test suite:
   \`\`\`bash
   pnpm test
   \`\`\`

4. Run the linter:
   \`\`\`bash
   pnpm lint
   \`\`\`

5. Commit your changes:
   \`\`\`bash
   git commit -m "feat: add new feature"
   \`\`\`

6. Push and open a pull request.

Commit conventions

If you use conventional commits or a specific format:

markdown
## Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` — New feature
- `fix:` — Bug fix
- `docs:` — Documentation only
- `refactor:` — Code change that doesn't fix a bug or add a feature
- `test:` — Adding or updating tests
- `chore:` — Maintenance tasks

Example: `feat: add dark mode toggle to settings page`

Pull request guidelines

Set expectations for the review process:

markdown
## Pull Requests

- Fill out the PR template completely
- Link to the related issue
- Include screenshots for UI changes
- Add tests for new functionality
- Update documentation if behaviour changes

### Review Process

- A maintainer will review your PR within 3 business days
- We may request changes — this is normal and collaborative
- Once approved, a maintainer will merge your PR

Code style

markdown
## Code Style

- We use ESLint and Prettier — run `pnpm lint` to check
- TypeScript strict mode is enabled
- Prefer named exports over default exports
- Write self-documenting code; add comments only for "why", not "what"

Optional but valuable sections

Reporting bugs

markdown
## Reporting Bugs

Open an issue with:
1. Steps to reproduce
2. Expected behaviour
3. Actual behaviour
4. Environment (OS, Node version, browser)
5. Screenshots if applicable

Use the bug report template when creating an issue.

Requesting features

markdown
## Requesting Features

Open an issue describing:
1. The problem you're trying to solve
2. Your proposed solution
3. Alternatives you've considered

We'll discuss the approach before implementation begins.

Financial contributions

If you accept sponsorships:

markdown
## Financial Contributions

If you'd like to support the project financially:
- [GitHub Sponsors](https://github.com/sponsors/owner)
- [Open Collective](https://opencollective.com/project)

Template

Here's a minimal CONTRIBUTING.md you can copy and adapt:

markdown
# Contributing

Thanks for your interest in contributing!

## Quick Start

1. Fork and clone the repo
2. Run `npm install`
3. Create a branch: `git checkout -b my-change`
4. Make changes and write tests
5. Run `npm test && npm run lint`
6. Push and open a PR

## Guidelines

- Write tests for new features
- Follow existing code style
- Keep PRs focused on one change

## Issues

- Bug? Open an issue with reproduction steps
- Feature idea? Open an issue to discuss first
- Questions? Use GitHub Discussions

Common mistakes

  1. No setup instructions. Assuming contributors can figure out the environment on their own.
  2. Outdated commands. Test your setup instructions from scratch periodically.
  3. No response timeline. Contributors get frustrated not knowing when they'll hear back.
  4. Too formal. An overly bureaucratic process discourages casual contributors.
  5. No small-task labels. Without "good first issue" labels, newcomers don't know where to start.

Complement your CONTRIBUTING.md

A good CONTRIBUTING.md pairs with a good README. Score your README to check if it's welcoming to contributors, or generate one that includes a contributing section.

For more on open-source documentation, read our complete guide to open-source documentation or check our open-source README template.