Writing a CONTRIBUTING.md People Actually Read

Most CONTRIBUTING.md files fail the same way: they are written for the maintainer’s peace of mind, not the reader’s goal. A new contributor - or a teammate joining the project, which is the same reader - wants three answers: how do I run this, how do I change it, and how do I get the change accepted. Write those, in that order, and stop.

1. Setup that actually works#

The first section is the one that gets read: clone, install, run. For a Laravel app that is the composer install, .env setup (which our env files guide covers properly), migrations, and the one command that proves it works - php artisan serve, npm run dev, the test suite.

The test is brutal and simple: hand the repo to someone who has never seen it and watch. Every place they stop is a line your guide is missing. Do this once a year, because setup rots.

2. The workflow, concretely#

Branch naming if you have a convention, what a pull request should look like (link your PR template if you have one), who reviews, and how long a review usually takes. That last one matters more than anything else in the file: “expect a first review within two working days” turns waiting from neglect into process.

Keep it to what a contributor does, not how the team philosophizes. Three paragraphs is plenty.

3. The bar for merging#

What CI must pass, whether commits get squashed (see squash merge or merge commit), any style tooling that will reject the PR - Pint, ESLint, whatever runs. Contributors forgive strict rules; they do not forgive discovering them in a red CI run after pushing.

What to leave out#

• Code of conduct boilerplate in the same file. Worth having, worth its own file - GitHub surfaces CODE_OF_CONDUCT.md separately.
• Architecture essays. Link the README or docs instead; a guide that takes twenty minutes to read gets zero minutes.
• Rules nobody enforces. Each one teaches the reader that the file is decorative, and then they skip the real rules too.

A contributing guide is a promise: follow this and your work lands. Every line either keeps that promise shorter or makes it longer. Keep the short ones.