contributor-experience

---
name: contributor-experience
description: Turn users into contributors and make their first PR succeed. Use when a project gets stars but no contributions, when first-time PRs stall or get abandoned, when writing or improving CONTRIBUTING.md, when setting up a dev environment that works on the first try, or when the user asks "how do I get contributors" or "why does nobody contribute". Covers the contribution funnel, good first issues, local setup, mentorship, recognition, and onboarding a contributor into a maintainer.
---

# Contributor Experience

Contributors are not recruited; they are **unblocked**. Almost everyone who could
contribute to your project already wanted to at some point and hit a wall. Find the
wall.

## The funnel

Each step loses most of the people at the previous one. Fix the leakiest step, not
your favorite one.

```
Uses the project        1000
Hits a bug/limitation    200
Considers fixing it       50   ← lost to: no clear entry point, unclear scope
Clones and sets up        20   ← lost to: setup fails on their machine  ★ biggest leak
Makes the change           8   ← lost to: can't find where, tests fail confusingly
Opens a PR                 5   ← lost to: process anxiety, CLA friction
Gets it merged             3   ← lost to: slow review, endless nits
Contributes again          1   ← lost to: no acknowledgment
```

The largest single leak in most projects is **setup**. It is also the cheapest to fix
and the least glamorous, which is why it stays broken.

## Setup that works on the first try

Target: `git clone` → working dev environment → passing tests, in **under 10 minutes,
with one command**, on macOS, Linux, and Windows.

```bash
git clone https://github.com/owner/repo && cd repo
make setup     # installs deps, sets up hooks, seeds fixtures
make test      # passes
```

Verify it the only way that works: **on a clean machine**, or better, a container.
Your laptop has fifteen things installed that you have forgotten about.

```bash
docker run --rm -it -v "$PWD:/w" -w /w node:22 sh -c 'make setup && make test'
```

Better still, ship a devcontainer (`.devcontainer/devcontainer.json`) or a Nix flake so
"works on my machine" stops being a category of problem. GitHub Codespaces then gives
contributors a zero-install path, which converts drive-by fixers who will never
configure a local toolchain for a one-line change.

Windows deserves explicit attention: it is where setup silently fails and where you
will never see the person who gave up. Test it, or say clearly in `CONTRIBUTING.md`
that WSL is required.

## CONTRIBUTING.md

Short, concrete, and ordered by what a contributor needs first. Everything else goes
in `docs/`.

```markdown
# Contributing

## Quick start
git clone ... && cd repo && make setup && make test

## Making a change
1. Open an issue first for anything over ~50 lines — saves us both time.
2. Branch from `main`. Name it anything.
3. Write a test. `make test` should be green.
4. Open a PR. Draft PRs are welcome; ask questions in them.

## What we're looking for
- Bug fixes: always welcome, no issue needed
- Docs: always welcome, including typos
- Features: please open an issue first — see Scope in the README
- Refactors: please open an issue first

## Standards
- Formatting is automatic: `make fmt`. Don't fight the formatter.
- Commits: anything readable. We squash-merge, so PR titles matter most.
- Sign off your commits (`git commit -s`) — we use the DCO.

## Review
One maintainer approval merges. We aim to respond within 3 days; ping if we don't —
that's not rude, it's helpful.

## Getting help
Open a draft PR, or ask in [Discussions](link). Nothing is too basic to ask.
```

The three lines that matter most, and are usually missing:

- **When to open an issue first.** Prevents the wasted-weekend PR that gets closed.
- **The review timeline.** Silence is the #1 reason PRs get abandoned; an honest
  "3 days" beats an implied "immediately".
- **Explicit permission to ask questions.** Most people will not, unless invited.

## Good first issues

A real one has: a clear problem statement, the file and rough line to look at, an
expected approach, how to verify, and a named person to ask.

```markdown
### Add `--quiet` flag to suppress progress output

**Context:** `widget build` always prints a progress bar. In CI this is noise.

**What to do:**
1. Add `--quiet` to the arg parser in `src/cli/args.ts` (see `--verbose` at line 42)
2. Thread it into `src/build/reporter.ts` — when set, skip the spinner
3. Add a test in `tests/cli/args.test.ts`; there's a similar one for `--verbose`

**Verify:** `widget build --quiet` prints only errors.
**Questions:** comment here or ping @maintainer. Happy to pair.
**Size:** ~30 lines.
```

Rules:

- **Maintain 5–10 open at all times.** An empty `good first issue` list converts nobody.
- **Never take them yourself.** It is tempting — it is a 20-minute fix — but that fix
  is an onboarding opportunity worth far more than 20 minutes of your time.
- **Do not let one person claim five.** Ask them to finish one first.
- **Unassign after two weeks of silence**, kindly, so the issue re-enters circulation.

## Making the first PR succeed

The first PR determines whether there is a second. Bias hard toward merging.

- **Respond within 48 hours**, even if only to say you have seen it.
- **Batch feedback into one review**, and prefix severity (see `code-review`).
- **Merge, then fix the nits yourself.** A perfect codebase with no contributors is a
  worse outcome than a slightly inconsistent one with ten.
- **Say thank you specifically**: "this also fixed the ordering bug in #390, which I
  hadn't connected."
- **Then point at the next thing.** "If you're up for it, #445 is a close relative."
  This single sentence is the difference between one contribution and ten.

## Recognition

People contribute for reasons that are not money: learning, reputation, belonging,
and the specific pleasure of being useful. Feed those.

- **Credit in the changelog and release notes**, by handle, every time.
- **`all-contributors`** to recognize docs, design, triage, translation, and support —
  not only code. The people who answer questions in your issue tracker are doing
  maintenance work and are almost never acknowledged for it.
- **Say what their change enabled**, not just that it merged.
- **Amplify externally** — a post naming a contributor costs you nothing and is worth
  a lot to someone building a career.
- **`Co-authored-by:`** when you finish someone's abandoned PR.

## Growing maintainers

The only real solution to maintainer burnout is more maintainers, and they are grown
from contributors, not hired.

Signals someone is ready: sustained contributions over months, good judgment in code
review, helping *other* contributors in issues, and disagreeing with you productively.
That last one matters most — a co-maintainer who defers to you on everything has not
reduced your load.

Onboard in stages so trust and access grow together: triage rights → review rights →
merge rights → release/publish rights. Ask them privately and directly; most people
will not volunteer because they assume they are not wanted. Write down what you expect
(response cadence, scope of authority, how to say no) so the role is bounded and
declinable later without drama.

## Diagnosing "stars but no contributors"

Work through these in order — the answer is usually near the top:

1. **Does setup work?** Try it in a clean container today.
2. **Are there open `good first issue`s?** Zero is the most common answer.
3. **How long did the last three external PRs wait for a first response?**
4. **Was the last external PR merged, or nitpicked to death?**
5. **Does `CONTRIBUTING.md` exist and is it accurate?**
6. **Is the codebase navigable?** One file with 3,000 lines and no comments blocks
   everyone but you.
7. **Do you accept help?** Some maintainers reflexively rewrite every contribution.
   Contributors notice, and stop.
8. **Is the project actually contributable?** A niche tool with 200 users may simply
   have no contributor pool — and that is fine, but stop treating it as a failure.

## Anti-patterns

- **Setup that requires undocumented tribal knowledge.**
- **`good first issue` that isn't one.**
- **Silence on a first PR.** The most damaging thing in this document.
- **Reviewing a first-timer's PR like a senior engineer's design doc.**
- **A CLA gate on a typo fix.**
- **Doing all the easy issues yourself.**
- **No acknowledgment after merge.**
- **"PRs welcome" as a way to close feature requests** without ever making one
  possible to write.
- **Treating contributors as free labor.** They are volunteers spending scarce time on
  your project. Act accordingly.