How to Write a CONTRIBUTING.md People Will Actually Follow

Most CONTRIBUTING.md files get written once, during a burst of project-launch energy, and never opened again — not by the maintainer, not by anyone else. The ones that actually get followed share three things. They say exactly what help is wanted. They spell out the setup steps a contributor needs before touching code. And they live where GitHub actually shows them.

Quick answer

A CONTRIBUTING.md that gets followed states setup steps, code expectations, and PR process in plain language, and sits where GitHub actually surfaces it — the `.github` directory, the repository root, or a `docs` folder, checked in that priority order. Get that right and GitHub does the promotion for you: the file shows up in a dedicated Contributing tab, a sidebar link, and a banner the moment someone opens an issue or pull request. Already worked through your README? This is the natural next file — the README says what the project is, CONTRIBUTING.md says how to help build it.

Step-by-step: writing a CONTRIBUTING.md people will follow

Open with what you're actually asking for

Skip "contributions welcome." It tells a contributor nothing about whether you want bug reports, documentation help, or a new feature — and it doesn't thank them for showing up in the first place. Open by naming the kinds of help you want: small bug fixes, docs, tests, a specific backlog item. If it's true, say so warmly. A guide that opens with gratitude and a specific ask reads differently than a wall of rules.

Document the exact setup path

This is the single highest-friction gap between someone wanting to help and someone actually opening a pull request. Don't describe the setup — paste it:

git clone https://github.com/your-org/your-project.git
cd your-project
npm install
npm test

Name the script to run, the environment variables to set, the exact lint and test commands. If your project has a CHANGELOG.md, mention briefly that it's where shipped changes get recorded — that keeps a contributor from confusing "what changed" with "how do I contribute."

Spell out the pull request process

Branch naming, if you enforce it. Commit message conventions, if you have them. And what happens after submission — does a maintainer review within a week, does CI have to pass first, is there a required checklist. None of this needs to be long. It needs to answer the question a contributor is actually asking: if I do this, what happens next?

Keep CONTRIBUTING.md, templates, and your CHANGELOG separate

These three files do different jobs, and folding them together makes all three worse. CONTRIBUTING.md carries the process and the philosophy. Issue and pull request templates standardize the repeated, structured asks — reproduction steps, a merge checklist — so you're not retyping the same request in every thread. A CHANGELOG.md records what shipped, not how to contribute to it. Keep each one doing its own job.

Common problems and fixes

Too vague to act on

"PRs welcome!" and nothing else tells a contributor nothing. Replace it with the specific setup and process steps above. A contributor who knows exactly what to run is far more likely to open a well-formed pull request than one guessing at your conventions.

Buried in the README, or missing entirely

Contribution steps that grow past a few lines belong in their own file, not tucked into the README under a header nobody scrolls to. Splitting them out keeps the README focused on what the project does — the same instinct behind a documentation style guide that keeps different kinds of docs in their own lane instead of one file trying to do everything.

Never updated after the workflow changes

A CONTRIBUTING.md that still references a build step you dropped six months ago is worse than no file at all — it wastes a contributor's first hour. Treat it as living documentation. Update it the same sprint you change the setup process, not whenever someone happens to notice it's stale.

Assuming the file guarantees compliance

It won't. Plenty of contributions still won't match the instructions given, no matter how clearly you write them. What a good CONTRIBUTING.md reliably does is raise the odds of a well-formed pull request and cut down on the same questions landing in your inbox every week. That's the honest case for maintaining one — not a promise that everyone reads it before they type.

Frequently Asked Questions

Where should CONTRIBUTING.md live in my repo?

In the .github directory, the repository root, or a docs folder — GitHub checks those three locations in that priority order and only shows the file from the highest-priority spot if you have duplicates. The repo root is the safest default for a small project.

What's the difference between CONTRIBUTING.md and issue templates?

CONTRIBUTING.md sets the overall philosophy and process — how to propose a change, how to get your dev environment running, what kind of help you're looking for. Issue and PR templates standardize the repeated, structured asks, like reproduction steps or a merge checklist. Use CONTRIBUTING.md for the story, templates for the form.

How long should a CONTRIBUTING.md be?

Long enough to answer "how do I get this running" and "what happens after I open a PR," short enough that someone reads the whole thing before their first commit. Most solid guides fit in under a page and only grow an FAQ section once the same questions start repeating.

Does a CONTRIBUTING.md guarantee people will follow it?

No — plenty of contributions still won't match the instructions. What it reliably does is raise the odds of a well-formed pull request and cut down on repeat questions, which is why contribution-dependent projects treat it as worth maintaining.

Doing this with Carets

A CONTRIBUTING.md is plain Markdown: headings, a fenced code block for the setup commands, a short list of expectations. That's exactly the kind of file Carets is built to edit. Syntax highlighting makes the command block and any config snippets easy to read at a glance, and every file stays organized alongside your other project docs in files, projects, and tags — so your README, CHANGELOG, and CONTRIBUTING.md sit together instead of scattered across apps.

Draft it on your Mac. Tighten a sentence on your iPhone between meetings. Review the setup steps on your iPad before you push. Carets is native and fast on all three, and the file stays plain Markdown the whole time — portable to wherever your repo actually lives. Carets is available on the App Store for iPhone, iPad, and Mac.