Open Source Contributing Guide Template
Four documents and two sheets, including the sheet that separates a rejection a checklist could have caught from one that never could.
Free download · No account needed
Every CONTRIBUTING.md guide on the first page of results is the same checklist of sections: a setup guide, a pull request workflow, a code of conduct, a link to issue templates. GitHub's own documentation explains what the file mechanically does, surface a link to it when someone opens an issue or a pull request, and stops there. None of it says anything about which of those sections actually stops a real pull request from getting closed without merging on your specific project.
A mixed-methods study of ten large, mature open-source projects curated 265,325 pull requests. An industrial report it cites put the baseline at 8 percent of pull requests wasted, meaning rejected or abandoned, industry-wide. Reading 354 abandoned ones by hand, the researchers found difficulty addressing a maintainer's comments, lack of review, and unresolved CI failures each present in more than 20 percent of them. This pack sorts your own closed-without-merging history into the same kind of categories, then marks each one preventable by a document, partially addressable, or a genuine judgment call no checklist fixes.
Loomwork, the open-source validation library in the worked example, ran that sort against twelve months of history: 240 external pull requests, 185 merged, 55 wasted at 22.9 percent, 2.9 times the industry baseline. Missing or failing tests was the single largest category at 14. 9 of those 14 traced back to one cause invisible from the pull request alone: an integration test dependency on a local Postgres extension that the setup documentation never named. The Setup Failure Log sheet is what surfaced it.
What's in the pack
Contribution Guide
The process from fork to merge, with every step traced to a rejection reason that actually recurred rather than to a generic best-practice list.
Setup Instructions
Written against the Setup Failure Log, so the step most likely to actually break gets the most detail instead of the least.
Code Standards
Covers only what the linter and formatter cannot enforce automatically: naming conventions, dependency policy, and what counts as adequate test coverage.
Review Expectations
States how long a first response takes and how many review rounds is normal, aimed at the largest category most guides never address at all.
Common Rejection Reasons
Every pull request that closed without merging in the trailing window, sorted by reason and marked preventable, partially addressable, or a judgment call.
Setup Failure Log
First-time setup attempts ranked by where they broke, joined against the rejection sheet to find gaps that read as a different problem from each side.
How to use it
- 1
Send what already exists
The repository, its build and CI configuration, and as much pull request history as you can gather, specifically including the ones that never merged.
- 2
Sort what did not merge
River sorts every closed-without-merging pull request into a reason, then marks it preventable, partially addressable, or a judgment call.
- 3
Join it against setup history
Any record of contributors getting stuck during setup gets checked against the rejection reasons for a connection invisible from either side alone.
- 4
Draft the four documents
The Contribution Guide and Setup Instructions absorb most of the preventable category; Code Standards and Review Expectations cover what is left.
Frequently asked questions
Is this template free?
Yes, and the download needs no account and no card. Edit with AI is the optional half: it reads your pull request history and sorts what closed without merging into the categories this pack is built around. Every other pack sits in the template library.
What format are the downloaded files?
Four documents as Word files and two sheets as CSVs, in one zip. The sheets arrive with the Loomwork rows in place as a worked example, so the categories are visible before you replace them with your own history.
We already have a CONTRIBUTING.md. What does this add?
A reason to trust which sections of it matter. Most contributing guides are a checklist of sections nobody has checked against actual outcomes. This pack sorts your own closed-without-merging pull requests first, so every section traces to something that actually recurred rather than to a generic template.
How do you tell a preventable rejection from a judgment call?
Preventable means a documented step would have caught the problem before a reviewer saw the diff: a missing dependency, an unrun formatter, an unsearched duplicate. A judgment call means the outcome depends on a maintainer's substantive decision, which no document settles in advance. Going quiet after feedback sits in between: documentation reduces it, but the residual cause is a contributor's own time.
What if we don't have enough closed-without-merging history to sort?
A smaller sample still finds a real pattern once a reason repeats across more than one contributor. A single occurrence of anything is left alone rather than promoted into a guide section on one data point, since the whole method depends on repetition being the signal, not any one incident.
How does this differ from documenting an inherited codebase?
Audience and direction. Inherited codebase documentation explains an existing codebase to whoever now has to maintain it. This pack explains the contribution process to someone outside the project entirely, using the project's own rejection history rather than its source code as the input.
What else belongs alongside this?
The references a contributor's change might touch. API documentation covers the reference a new endpoint needs, and the technical debt register shows which modules cost the most to change, which is useful context before a contributor's first pull request lands in one of them.
Find out which rejection reason is actually costing you contributors
Take the Word documents and CSV sheets blank, or open this exact pack in River and send it your pull request history.
Edit with AI