Template CONTRIBUTING

CONTRIBUTING.md: the contributor's manual of an open source project

If README.md is the visitor's pitch, CONTRIBUTING.md is the contributor's manual. It is the document that turns an interested stranger into a productive co-author, and the absence of it is the most common reason healthy projects fail to scale beyond their original maintainer. GitHub itself auto-discovers the file: when a user opens a new issue or pull request, the platform automatically renders a "Please read our contributing guidelines" link if the file exists, raising compliance dramatically without any custom work.

The classical sections are well established. A canonical CONTRIBUTING.md covers: link to the Code of Conduct, how to report bugs (ideally pointing at an .github/ISSUE_TEMPLATE), how to suggest features, development setup (clone, install, env), coding standards (style guide, formatter, linter), Git workflow (branch naming, commit message style — Conventional Commits is the de facto standard), testing requirements, the pull request process, the review process, and finally the communication channels (Discord, Slack, mailing list).

Code of Conduct, CLA and DCO

Three legal and cultural artifacts often referenced from CONTRIBUTING. The Code of Conduct lives in its own file (CODE_OF_CONDUCT.md) — the overwhelming standard is the Contributor Covenant by Coraline Ada Ehmke, adopted by Linux, Kubernetes, Node.js and thousands of others. A CLA (Contributor License Agreement) is required by some corporate-backed projects (Google, Facebook, the Apache Foundation) and assigns or licenses contribution copyright to the entity. A lighter alternative is the DCO (Developer Certificate of Origin), used by the Linux kernel: contributors add Signed-off-by: to each commit and assert they have the right to submit the change.

Gradient onboarding and contributor experience

Successful projects design a contribution ladder: first-time visitors find good first issue and help wanted labels, then graduate to regular issues, then to triage and review. The First Timers Only initiative formalised this — labels and welcoming language designed for absolute newcomers. Mentorship programs amplify the funnel: Outreachy, Google Summer of Code, Rails Girls Summer of Code pay people to make their first patches. Recognition matters too — the All Contributors spec uses emoji-based attribution (code, docs, design, review) so non-code work shows up in the README.

Tooling: linters, hooks, CI and funding

A modern CONTRIBUTING is half social contract, half tooling reference. Pre-commit hooks via husky + lint-staged (Node) or pre-commit (Python) enforce formatting locally. CI runs the same suite — GitHub Actions, CircleCI and the older Travis CI are the usual choices. Style is enforced by Prettier + ESLint for JS, Black + ruff for Python, gofmt for Go. Documentation sites use Docusaurus, ReadTheDocs or VitePress. Cultural rituals — Hacktoberfest every October — drive seasonal contribution waves. And the funding section, with GitHub Sponsors, Open Collective or Patreon links, makes sustainability explicit.

FAQ

Is CONTRIBUTING.md mandatory? Not technically — your repo will work without it. In practice, any project that wants outside contributions needs one; the absence signals "I am not ready for collaborators yet" and most experienced contributors will move on.

How long should it be? One to three screens. Long enough to cover setup, style and PR process; short enough that someone will actually read it before opening a PR. Hand off detail to linked files (CODE_OF_CONDUCT, dev docs, ADRs).

Should it be bilingual? If you are courting global contributors, yes — keep the canonical version in English (the de facto language of open source) and provide translations. The freeCodeCamp contributing guide is a great reference: it is translated into dozens of languages and uses the README convention of one link per locale at the top.

CONTRIBUTING.md or a wiki page? The file in the repo wins. It version-controls together with the code, GitHub auto-discovers it on issues and PRs, AI tools index it, and forks carry it. Wikis are great for evolving notes, but the contribution rules belong with the source.