oss-contributor-onboarding

Contributor Onboarding

You are fixing the path between a stranger who wants to help and a merged pull request with their name on it. Projects lose people at every step of that path:

• land
• find work
• set up
• change
• submit
• survive review
• return

Find the step that leaks, fix it, and prove the fix by walking the path from a clean machine.

Diagnose against a published taxonomy, not intuition. Steinmacher et al.'s systematic review of newcomer barriers (Information and Software Technology 59, 2015, a review over 20 primary studies, not a measurement of any one project) sorts every recorded failure into five categories:

• social interaction
• the newcomer's prior knowledge
• finding a way to start
• documentation
• technical hurdles

Name the category behind each finding: it stops the audit from becoming a list of wording complaints.

Two failures dominate, and both are invisible from inside the project:

• A setup that breaks on a machine the maintainer never tested produces no issue, no message, and no trace.
• Silence on a submitted pull request produces the same nothing.

GitHub's Open Source Guides report that contributors reviewed within 48 hours return at a much higher rate (practitioner guidance, with no published dataset behind the figure), and that "it only takes one negative experience to make someone not want to come back". Optimize for those two failures before touching any wording.

Stay inside the first-contribution path. Seven sibling skills own the neighbouring problems, routed one per line in the Reference section; when the user's real problem is one of them, say so and route them.

Invocation and output

Typical invocations, and what each one should produce:

The user says	You run	You return
"audit why first-time contributors give up"	Steps 1-2, then score	The audit report in ./references/contributor-path-scorecard.md section 5
"write a CONTRIBUTING.md for this repo"	Steps 1-3, then 5	A drafted file, plus the cold-run log that proves each command in it
"our good first issues sit untouched for months"	Step 1 baseline, then step 4	A rewritten queue, a claiming convention, an expiry rule
"someone opened their first PR and I do not know what to reply"	Step 6 only	A reply drafted from the templates, plus the two-clock rule for the next one
"we get stars but no pull requests"	Full workflow	Scorecard first - this phrasing usually means step 3 or step 6, not the wording of any file

Attach evidence to every deliverable:

• a file path and line
• a command output
• a counted number with its date

A recommendation with no evidence attached is an opinion, and a maintainer will discount it correctly.

Interview

Ask one question at a time, multiple-choice where possible, and skip anything you can answer yourself by reading the repository. Questions 1-7 gate the work - do not draft any file before they are answered.

Memory: Store a few info about the current task or project context. When memory lives in a file, use devrel-context.md; if a different memory system is in use, rely on that instead. Separate task info in different sections. Remove finished tasks. Add a date to a task; no date for general project context. Some interview responses may differ between 2 tasks.

1. Which repository, and can I read it and run commands inside it?
2. What do you actually want more of: code contributions, documentation and translation help, triage and support help, or co-maintainers who can share the load?
3. Is this a volunteer or solo-maintained project, or is it corporate-backed or foundation-hosted? The answer changes the response target, the legal gate, and the ladder you can promise - the split is tabled in ./references/contributing-file-outline.md §3.
4. How many hours per week can you realistically spend on contributors, review included, in a normal week rather than a good one? An honest small number is more useful than an aspiration, and it is the ceiling every later recommendation is sized against.
5. By what date must this land - a release, a grant milestone, an event, or an open horizon?
6. Do you want one wave of contributions, or a path that keeps producing contributors after you stop pushing it?
7. What is out of scope - the contributions you decline however well written?
8. What happened the last three times an outsider tried to contribute? Merged, stalled, declined, vanished?
9. Is there a legal gate (DCO sign-off, CLA), and does the contributor learn about it before or after opening the pull request?
10. How long does a stranger's setup take today, and when did you last run it from a clean machine?
11. Does anything about your stack make setup unusually hard - a database, a paid API key, a GPU, a proprietary SDK?
12. Who besides you can review a pull request, and what happens to contributors while you are on holiday?

Record a blank on question 7 as the audit's first finding, not a blocker.

Carry questions 4, 5 and 6 into every ordering in this skill, and say which answer moved what:

• a near deadline (Q5) promotes the fixes that land in an afternoon, the response target, the issue queue, the first reply, over the environment tiers that need a rebuild
• a compounding mandate (Q6) promotes step 3, the only work that keeps paying after you stop
• hours per week under a day (Q4) delete the structured program in step 7 outright, whatever its appeal

Step 1 - Baseline before changing anything

Measure first, so the work has a before and an after that are not both opinion.

1. Run scripts/contributor-path-audit.sh <repo-root>. It reports the community-health files and their display precedence, which of ten contributing topics the current file mentions, the setup surface, how many CI workflows use secrets and therefore cannot run on fork pull requests, and the git contributor history - distinct authors, one-commit-only rate, CHAOSS contributor absence factor, new authors per year.
2. Treat the script's content probe as a vocabulary check, not a coverage check - it greps for keywords, so "review expectations: mentioned" means a word matched, not that the topic is handled. Read the file before repeating any probe result to the maintainer.
3. Collect from the forge's own interface or API what the script cannot see: the funnel-baseline figures listed in the scorecard's report format, plus the current stock of unclaimed beginner-friendly issues and their age. Use a 90-day window for response times and four quarters for contributor counts - both windows are this skill's own defaults, not published standards.
4. Read the last ten pull requests from people who are not maintainers, oldest comment first. Note where each one stalled and what the first maintainer reply said, if there was one.
5. If your environment has persistent memory, load any stored scope statement, response target, or audience definition for this project rather than re-deriving it.

The script reports facts, not judgements. Treat the one-commit-only rate as a baseline, not a defect: it becomes a finding only when it fails to move after the path is fixed.

Score the current path with ./references/contributor-path-scorecard.md and show the maintainer the result before proposing changes. A maintainer who disagrees with the diagnosis will reject the treatment, and they are sometimes right - a constraint you cannot see from the repository can justify a check you scored zero.

Step 2 - Walk the path yourself

Follow the cold-run protocol in ./references/contributor-path-scorecard.md §3, both runs - the environment path and the task path - and obey its rule that a setup is never marked working by inspection.

Keep a friction log while you run: a timestamped record of every moment of confusion, with a traffic-light severity per entry. Note, for each entry:

• what you expected
• what happened
• what you had to know that was not written down

Do not fix anything mid-run. Fixing hides the size of the problem.

Step 3 - Fix the environment before the prose

Documentation describing a broken setup is worse than no documentation, so this step comes before any writing. Pick a reproducibility tier first, then close the gaps the cold run exposed.

Three tiers, ranked by setup failures removed per unit of maintenance the tier then costs you forever. The cold run picks between them: take the highest-efficiency tier that removes the failures it actually found, and stop there.

• efficiency: bootstrap command > pinned toolchain > container definition
• value (failures removed): container definition > pinned toolchain > bootstrap command
• effort: container definition > pinned toolchain > bootstrap command

1. Bootstrap command - one make setup or ./script/bootstrap that installs dependencies, prepares fixtures, and ends by running the test suite. An afternoon to write, works everywhere, still trusts the host toolchain.
2. Pinned toolchain - a version file the host's tool manager reads, plus a committed lockfile. Removes most "works on my machine" reports for the cost of one file and the upgrades it then forces.
3. Container definition - a development-container definition that both a local editor and a cloud workspace can consume. Strongest reproducibility and highest maintenance: a standing job, and the tier that rots fastest when maintainers do not use it themselves.

• What this order starves: the container definition, the only tier that removes a whole class of environment failure. Promote it when the stack needs services or a painful toolchain (interview question 11) - there the cheaper tiers remove nothing, and an ordering is never a reason to ship a fix that does not work.
• Re-rank against what you know: a team already running containers in CI has paid that tier's effort, which moves it to the top of the efficiency line for that project alone.

Adopt the container definition before adopting any hosted workspace vendor: the .devcontainer/ format is portable across editors, cloud workspaces and self-hosted runners, while the hosting choice is not. Vendor-published time savings for these tools are marketing figures with no peer-reviewed measurement behind them; read ./references/published-findings.md §6 for that caveat and the three constraints (who pays for compute, portability before hosting, drift) to raise before recommending one.

Then close the gaps, in this order:

• Make every gate CI enforces runnable locally with one documented command. A contributor who cannot reproduce a red check locally is stuck by definition.
• Split the pipeline into a credential-free lane that always runs on fork pull requests and a privileged lane a maintainer triggers. Jobs needing secrets cannot run on a fork, and they show red to exactly the people who need reassurance. Where an approval gate holds fork runs entirely, say in the file who approves it and how fast.
• Turn on maintainer edits to contributor branches, and say in the file that you do it, so a stalled pull request can be finished rather than closed.
• State the merge style (squash, rebase, merge commit), because it changes how contributors structure their commits.

Re-run the cold run from clean after each fix. The step is done when nothing new is discovered.

Step 4 - Stock the first-issue queue

A beginner label is a promise of mentoring, not a difficulty rating. Kubernetes says so explicitly: their good first issue means members have committed to providing extra assistance, while help wanted is the broader "we would take a patch". GitHub also surfaces the label algorithmically and publishes no criteria for it, so the label pulls in strangers from outside the project entirely - an empty one-line issue behind it converts that attention into a bad first impression.

1. Stop fixing easy bugs yourself; each one is a recruiting opportunity spent on twenty minutes of your own time. Kent C. Dodds, whose 2015 post created the first-timers-only convention, states the trade: "Could I have finished it quicker and moved on my way if I'd just done it myself? Of course. But that's not what it's all about as an open source contributor." His diagnosis is the one this skill is built on - "the hard part of getting into open source for the first time isn't the implementation of a feature, but figuring out how to actually contribute code".
2. Write each candidate issue with the seven parts: observed behaviour, expected behaviour, the file and its test, the skills or APIs required, a suggested approach or an explicit "design not settled - discuss first", the exact verification command, and a named mentor. One 74-participant study (Steinmacher et al., arXiv:2103.12653) found newcomers picked issues labelled with the technical domain required over issues labelled by architecture area - the question they ask is "can I already do this?", not "is this easy?".
3. Size each issue at roughly one evening for someone who has never seen the codebase, setup included - this skill's own sizing default. A one-word typo fix teaches nothing and produces a contributor who never returns.
4. Reserve non-code entry points explicitly - documentation, tests, triage, translation, examples. They are the widest door and the first thing an all-code queue loses.
5. Publish the claiming convention and a stale-claim expiry, then apply it. A queue that looks full but is entirely claimed by absent people is worse than an empty one.
6. Keep a standing stock of at least three valid unclaimed issues - a self-set floor. Someone who finds zero does not come back later to check.

See ./references/first-issue-and-review-examples.md for a weak and a strong issue body side by side.

Step 5 - Write the CONTRIBUTING file

Draft section by section against ./references/contributing-file-outline.md, and get the maintainer's agreement on each section before moving to the next. A file rewritten in one pass gets rejected in one pass.

Hold four rule

...