Contributing guidelines template (Markdown)

This template covers the sections most projects need. Replace the placeholders with your project's actual commands, branch names, and contacts, and delete the sections that do not apply.

Need it as a document? Paste the filled-in template into the free Markdown to Word or Markdown to PDF converter.

Copyable Markdown CONTRIBUTING.md template

# Contributing to [Project name]

Thank you for your interest in contributing. This guide explains how to report problems, suggest changes, and submit pull requests.

## Code of conduct

This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to follow it. Report unacceptable behavior to [contact email or link].

## Ways to contribute

- Report a bug
- Suggest a feature or improvement
- Improve the documentation
- Fix an issue labeled `good first issue` or `help wanted`
- Review open pull requests

## Asking questions

Use [Discussions, forum, or chat link] for questions. The issue tracker is for bugs and feature requests.

## Reporting bugs

1. Search [existing issues](https://github.com/[owner]/[repository]/issues) to check whether the bug is already reported.
2. If it is not, open a new issue using the bug report template.
3. Include the version, operating system, steps to reproduce, expected result, and actual result.

## Reporting security issues

Do not open a public issue for a security vulnerability. Follow the process in [SECURITY.md](SECURITY.md).

## Suggesting features

Open an issue describing the problem you want to solve, who it affects, and the change you propose. For large changes, wait for maintainer feedback before starting work.

## Setting up the development environment

**Requirements:** [Language or runtime and version], [other tools]

```bash
git clone https://github.com/[your-username]/[repository].git
cd [repository]
[install dependencies command]
[run tests command]
```

## Making changes

1. Fork the repository and create a branch from `[main]`: `git checkout -b [type]/[short-description]`
2. Make your change in small, focused commits.
3. Add or update tests for the change.
4. Update documentation when behavior changes.
5. Add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for user-facing changes.
6. Run the checks below before opening a pull request.

## Style and checks

- **Formatting:** [Formatter and command]
- **Linting:** [Linter and command]
- **Tests:** [Test command]
- **Commit messages:** [Convention, for example: short imperative summary under 72 characters]

## Opening a pull request

- Link the related issue, for example `Closes #123`.
- Describe what changed and why.
- Include screenshots for visible changes.
- Keep each pull request to one logical change.
- Make sure all checks pass.

## Review process

A maintainer will review your pull request within [time frame]. Reviewers may ask for changes. When the pull request is approved and checks pass, a maintainer will merge it.

## License

By contributing, you agree that your contributions will be licensed under the [License name] license that covers this project. [Add any Contributor License Agreement or Developer Certificate of Origin requirement here.]

## Getting help

Contact [maintainer name, team, or channel] if you are unsure how to proceed.

What contributing guidelines are for

Contributing guidelines save time on both sides. Contributors learn what maintainers expect before they invest effort, and maintainers receive issues and pull requests in a form they can act on. Without a guide, the same questions about setup, branch names, tests, and review come up in every pull request.

The guide is also where a project sets expectations: what kinds of contributions it accepts, how decisions are made, and how long a review usually takes. Stating these up front reduces stalled pull requests and duplicated work.

Make the first contribution easy

Many first contributions are documentation fixes or small bugs. Make those paths short:

• Label suitable issues good first issue or help wanted, and mention the labels in the guide.
• Say whether a contributor should comment on an issue before starting work, especially for large changes.
• Keep the development setup to a few commands. If setup is long, link to a separate document and keep the summary in CONTRIBUTING.md.

Describe the pull request workflow

State the base branch, the branch naming convention if you have one, the checks that must pass, and what a pull request description should contain. On GitHub, a keyword such as Closes #123 in the pull request description links the pull request to the issue and closes the issue when the pull request is merged into the default branch.

If the project keeps a CHANGELOG.md, ask contributors to add an entry under Unreleased in the same pull request. Entries written alongside the change are more accurate than entries reconstructed at release time.

Separate conduct, security, and licensing

Contribution guidelines link to three related files rather than repeating them:

• CODE_OF_CONDUCT.md sets behavioral expectations and explains how to report violations.
• SECURITY.md explains how to report vulnerabilities privately.
• LICENSE states the terms that cover contributions. If the project requires a Contributor License Agreement or a Developer Certificate of Origin sign-off, say so in the guide and explain how to complete it.

Each of these is a GitHub community health file. CODE_OF_CONDUCT.md, CONTRIBUTING.md, and SECURITY.md can be set as account-wide defaults in a public .github repository. A license cannot be set as a default and must be added to each repository.

Completed contributing guide excerpt

## Making changes

1. Fork the repository and create a branch from main:
   git checkout -b fix/empty-header-crash
2. Run the tests before and after your change:
   npm test
3. Add a test that fails without your fix.
4. Add a line under "## [Unreleased]" in CHANGELOG.md.

## Opening a pull request

- Link the issue: "Closes #482".
- Explain what changed and why in two or three sentences.
- One logical change per pull request.

A maintainer usually responds within five working days.

The excerpt gives contributors exact commands, a clear definition of done, and a realistic response time. The branch name, issue number, and response time are illustrative. Use your project's real values.

What to include in CONTRIBUTING.md

CONTRIBUTING.md FAQ

Where should I put CONTRIBUTING.md?

In the repository root, the docs folder, or the .github folder. The root is the most visible location for people browsing the files. If more than one copy exists, GitHub uses the one in .github first, then the root, then docs.

Can one CONTRIBUTING.md apply to all my repositories?

Yes, on GitHub. Add it to a public repository named .github in your organization or personal account. GitHub uses it as the default for any repository that does not have its own CONTRIBUTING.md.

What is the difference between CONTRIBUTING.md and a code of conduct?

CONTRIBUTING.md explains the process for contributing: issues, setup, pull requests, and review. A code of conduct sets behavioral expectations for everyone in the community and explains enforcement. Link the code of conduct from the contributing guide.

Do small projects need a CONTRIBUTING.md?

A short one helps even small projects. A few lines on how to report bugs, how to run the tests, and whether pull requests are welcome answer the questions new contributors ask most often.

Should CONTRIBUTING.md include coding style rules?

Include the commands that check style, such as a formatter and linter, rather than long prose rules. Automated checks are easier to follow and enforce than a written style guide.

Related templates

• README template
• CHANGELOG.md template
• Bug report template
• Architecture decision record template
• All Markdown templates

Sources

• GitHub Docs: Setting guidelines for repository contributors
• GitHub Docs: Creating a default community health file
• GitHub Docs: Linking a pull request to an issue
• Keep a Changelog 1.1.0