River
Y CombinatorBacked by Y Combinator
Log InStart Free
FREE TEMPLATE

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.

Edit with AIDownload (.docx + .csv)

Free download  ·  No account needed

What you get

Pack of 6 files: 4 documents, 2 spreadsheets

Open Source Contributing Guide Template
  • Contribution GuideDocument
  • Setup InstructionsDocument
  • Code StandardsDocument
  • Review ExpectationsDocument
  • Common Rejection ReasonsSpreadsheet
  • Setup Failure LogSpreadsheet

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.

The rejection that reads as a testing problem, until you check the other sheet

The Common Rejection Reasons sheet and the Setup Failure Log it is joined against.

Open Source Contributing Guide Template
RiverCommon Rejection Reasons

Common Rejection Reasons

55 pull requests closed without merging over twelve months for a fictional validation library, Loomwork. Sorted by primary reason.

ReasonCount% of 55Preventable?
Missing or failing tests1425.5%Yes
Went quiet after review feedback1323.6%Partially
Wrong target branch814.5%Yes
Lint or format failures712.7%Yes
Duplicate of in-flight work610.9%Yes
Breaking change, no discussion47.3%No
Missing CLA or DCO sign-off35.5%Yes

38 of the 55, 69.1 percent, are preventable by a document. Only 4, the breaking-change category, are a genuine judgment call no checklist could have settled in advance.

Going quiet after feedback is the second-largest category and the reason Review Expectations exists as its own document rather than a footnote.

RiverSetup Failure Log

Setup Failure Log

40 first-time setup attempts logged from discussion-forum questions over the same window.

StepFirst blocked here% of 40
Runtime version12.5%
Dependency install12.5%
Environment file25.0%
Integration tests needing local Postgres + citext1127.5%
Sailed through clean2562.5%

11 of 15 total setup failures, 73.3 percent, were the same undocumented Postgres dependency. Unit tests never touch it, so they passed cleanly and gave the contributor false confidence.

9 of those 11 opened a pull request anyway. All 9 land in the other sheet's "missing or failing tests" row, 64.3 percent of that category, for a cause the pull request diff never shows.

Edit with AI

What's in the pack

01

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.

02

Setup Instructions

Written against the Setup Failure Log, so the step most likely to actually break gets the most detail instead of the least.

03

Code Standards

Covers only what the linter and formatter cannot enforce automatically: naming conventions, dependency policy, and what counts as adequate test coverage.

04

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.

05

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.

06

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. 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. 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. 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. 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.

Sources

  1. GitHubSetting guidelines for repository contributors (opens in a new tab)
  2. arXiv8 percent of pull requests wasted (opens in a new tab)

Written by

Chandler Supple

Co-founder & CEO, River

Chandler has spent the last six years working in AI, building tools for millions of users and Fortune 100 companies. In 2025, he co-founded River to build a new kind of operating system for AI agents.

LinkedInGitHubX

Reviewed by

Brian Joseff, Co-founder, River

LinkedInX

More free templates

API Deprecation Policy Template

Free API deprecation policy template: the notice list built from real usage, the callers you can actually reach, and a window derived from how often they ship.

API Documentation and Reference Template

Free API documentation template in Word and CSV, with the two registers a generator cannot produce: undeclared failures, and examples that do not validate.

Partner Integration Guide Template

Free partner integration guide template built from real support tickets, split into what was already documented and what never was.

Technical Debt Tracking Register

Free technical debt tracking template that measures what each module costs to change, in engineering hours per year, instead of scoring it one to five.

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