CONTRIBUTING.md Builder
A CONTRIBUTING.md file welcomes new contributors and tells them exactly how to participate. Hosting platforms surface it automatically when someone files an issue or pull request. This builder assembles a complete, well-structured guide from a few inputs, so your project ships clear expectations from day one.
How it works
The builder composes Markdown sections from your inputs and toggles. It always includes an introduction and a how-to-contribute overview, then conditionally adds: reporting bugs, requesting features, the development setup, the pull request workflow, coding standards keyed to your stack, a commit message convention (optionally Conventional Commits), and a code of conduct link. Each section is templated with sensible defaults you can edit after copying.
What goes in each section
A complete CONTRIBUTING.md typically covers six areas, each solving a specific confusion that slows down first-time contributors:
Introduction and scope. Who is this guide for? Can external contributors submit patches, or only report bugs? Setting expectations up front prevents frustration when a contributor spends hours on a feature only to learn it will not be accepted.
Reporting bugs. What information the project needs to reproduce the issue: OS, language version, minimal reproduction steps, expected versus actual behaviour. A structured template here reduces the back-and-forth that burns maintainer time.
Feature requests. Where to discuss new ideas before building them. Many projects use a Discussions tab or a specific issue label for this. Directing contributors to discuss before coding prevents rejected PRs and wasted effort.
Development setup. The exact commands to clone, install dependencies, and run tests locally. Every project has a different setup; vague instructions like “set up the dev environment” are useless. Reference the actual package manager and any required external services.
Pull request workflow. The mechanics of contribution:
1. Fork the repo and create a branch from main.
2. Make your change.
3. Add tests for any new behaviour.
4. Run the full test suite and linter to confirm nothing is broken.
5. Open a pull request with a description of the change and why it is needed.This section is the most important for external contributors. Spelling it out reduces low-quality PRs and helps contributors self-qualify.
Commit message convention. If your project uses Conventional Commits or another format, state it here. Consistent commit messages enable automated changelogs and semantic versioning tools. Even if you do not have automation yet, establishing the convention now makes it easy to adopt later.
Stack-specific coding standards
The builder references your chosen language or framework in the coding standards section. For JavaScript/TypeScript projects, this typically means ESLint and Prettier; for Python, Black and pylint or flake8; for Go, gofmt. Naming the actual tools — rather than writing “maintain consistent style” — lets contributors check their work before submitting and reduces style-only review comments.
When to link a code of conduct
Public projects should always link a code of conduct. The Contributor Covenant is the most widely adopted template and signals that the project has thought about community standards. Keep the code of conduct in a separate CODE_OF_CONDUCT.md rather than embedding it in CONTRIBUTING.md — it deserves its own prominent file and GitHub surfaces it separately in the community health panel.
Reference your actual tooling so contributors know what runs in CI. If you adopt Conventional Commits, pair it with an automated release tool.