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:

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.