Skip to main content
A CONTRIBUTING.md file documents how people can contribute to your repository. It clarifies expectations, streamlines the contribution process, and reduces friction for maintainers and contributors alike. Why include a CONTRIBUTING.md
  • Improves onboarding for new contributors.
  • Sets clear guidelines for reporting bugs and proposing features.
  • Documents project-specific workflows (branching, commit messages, PR process).
  • Enables GitHub to surface the guidelines in the issues and pull request flows.
What to include (typical sections) Where to put the file
  • Create CONTRIBUTING.md at the repository root or inside the .github directory. GitHub displays the content in issue and PR flows when present.
Example workflow (create the file and push it to the repo)
  1. Add a new file: .github/CONTRIBUTING.md (or CONTRIBUTING.md at the repo root).
  2. Populate it with the sections above, replacing placeholders with project-specific links and examples.
  3. Commit and push the change so it’s discoverable in the repository.
Example git commands:
Back in the repository view you should see the new file listed with the recent commit message.
The image shows a GitHub repository page with directories and files listed, along with recent commit messages. On the right, there is a brief description of the repository and options related to repository management and settings.
How contributors see the file
  • When a contributor opens a new issue or creates a pull request, GitHub will show a reminder if your repository includes contribution guidelines.
  • The reminder appears as a short prompt like “contributions to this repository should follow its contributing guidelines” and links directly to the CONTRIBUTING.md file so contributors can review it before submitting.
The image shows a GitHub interface with a pop-up window for creating a new issue in a repository named "block-buster." The window includes a form for inputting screenshots, device information, and additional context.
Best practices for writing your CONTRIBUTING.md
  • Be specific and actionable: provide step-by-step setup instructions and exact commands for tests and builds.
  • Link to related documents: CODE_OF_CONDUCT.md, issue/PR templates, and relevant project docs.
  • Keep it up to date: revise the file when workflows, CI, or maintainers change.
  • Make it welcoming: include a short thank-you and clear next steps for first-time contributors.
  • Use examples: show a sample issue report and a sample PR description to set expectations.
  • Document automation: clarify required CI checks, labels, and who handles approvals and merges.
Additional resources
Place CONTRIBUTING.md at the repository root or in the .github directory. GitHub automatically links to it from the new issue and pull request interfaces, helping contributors follow your project’s process.

Watch Video