Contributor Experience

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.

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.

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

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

### 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 issues? 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.