oss-contributor-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
你正在修复从一位想要帮助的陌生人到一条带着他们名字的已合并 pull request 之间的路径。项目在路径的每一步都会流失人:
  • 着陆
  • 找到任务
  • 搭建环境
  • 进行修改
  • 提交
  • 通过评审
  • 再次回来
找出泄漏的那一步,修复它,并用一台全新机器走一遍完整路径来证明修复有效。
依据已发表的分类体系而不是直觉来做诊断。Steinmacher 等人对新人障碍的系统综述(Information and Software Technology 59, 2015;覆盖 20 项主要研究,并非对单个项目的测量)把记录到的所有失败归为五类:
  • 社交互动
  • 新人已有的知识
  • 找到开始的方式
  • 文档
  • 技术障碍
为每一条发现标注其背后的类别:这能让审计不至于变成一份措辞抱怨清单。
有两种失败占主导地位,而且从项目内部都看不见:
  • 一个在维护者从未测试过的机器上会坏的搭建流程,不会产生 issue、消息或任何痕迹。
  • 对已提交 pull request 的沉默,同样什么也不会产生。
GitHub 的 Open Source Guides 报告称,48 小时内得到评审的贡献者再次回来的比例要高得多(这是实践者指南,背后没有已发布的数据集),并且“只需一次负面体验就会让一个人不想再回来”。在改动任何措辞之前,先针对这两种失败做优化。
把范围限定在首次贡献路径内。有七个姊妹 skill 分别处理相邻问题,在 Reference 一节中每行路由一个;如果用户的真实问题是其中之一,请明确说明并路由过去。

Invocation and output

调用方式与输出

Typical invocations, and what each one should produce:
The user saysYou runYou return
"audit why first-time contributors give up"Steps 1-2, then scoreThe audit report in ./references/contributor-path-scorecard.md section 5
"write a CONTRIBUTING.md for this repo"Steps 1-3, then 5A 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 4A rewritten queue, a claiming convention, an expiry rule
"someone opened their first PR and I do not know what to reply"Step 6 onlyA reply drafted from the templates, plus the two-clock rule for the next one
"we get stars but no pull requests"Full workflowScorecard 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.
典型调用,以及每种调用应产生的结果:
用户说你执行你返回
“审计为什么首次贡献者放弃”步骤 1-2,然后打分./references/contributor-path-scorecard.md 第 5 节中的审计报告
“为这个仓库写一个 CONTRIBUTING.md”步骤 1-3,然后 5一份草拟的文件,加上证明其中每条命令都有效的冷启动运行日志
“我们的 good first issues 数月无人问津”步骤 1 基线,然后步骤 4重写后的 issue 队列、认领约定、过期规则
“有人开了他们的第一个 PR,我不知道该回什么”仅步骤 6根据模板起草的回复,加上下次回复的双时钟规则
“我们有很多 star 但没有 pull requests”完整工作流先出评分表——这种说法通常意味着步骤 3 或步骤 6 的问题,而不是任何文件的措辞
为每项交付物附上证据:
  • 文件路径和行号
  • 命令输出
  • 带日期的计数数字
没有附带证据的建议只是观点,维护者会很正确地打折扣。

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.
  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
一次只问一个问题,尽可能用选择题;凡是自己读仓库就能回答的问题就跳过。问题 1-7 是工作门槛——在这些问题得到回答之前不要起草任何文件。
  1. 哪个仓库?我可以读取它并在其中运行命令吗?
  2. 你实际更想要什么:代码贡献、文档和翻译帮助、triage 和支持帮助,还是能分担负担的共同维护者?
  3. 这是志愿者维护或单人维护的项目,还是有公司支持或基金会托管?答案会改变响应目标、法律门槛和你能承诺的成长阶梯——差异见 ./references/contributing-file-outline.md §3。
  4. 在一个平常周(而不是状态好的周)里,你实际能投入多少小时在贡献者身上,包括评审?诚实的小数字比愿望更有用,它是后续所有建议的规模上限。
  5. 这件事必须在什么日期前落地——发布、资助里程碑、活动,还是开放时限?
  6. 你想要一波贡献,还是一条在你不再推动后仍能持续产生贡献者的路径?
  7. 什么不在范围内——无论写得多好你都会拒绝的贡献?
  8. 最近三次外部人员尝试贡献时发生了什么?合并了、停滞了、被拒绝了、还是消失了?
  9. 是否有法律门槛(DCO 签署、CLA)?贡献者是在打开 pull request 之前还是之后才知道?
  10. 如今一个陌生人完成环境搭建需要多久?你上一次在全新机器上跑通是什么时候?
  11. 你的技术栈有没有让搭建特别困难的地方——数据库、付费 API key、GPU、专有 SDK?
  12. 除了你之外还有谁能评审 pull request?你休假时贡献者会怎么样?
如果问题 7 留空,把它记录为审计的第一条发现,而不是阻塞项。
把问题 4、5、6 带入本 skill 的每一个排序决策,并说明哪个答案改变了什么:
  • 临近截止日期(Q5)会把一个下午就能完成的修复、响应目标、issue 队列、首次回复,提升到需要重建的环境层级之上
  • 持续复利型任务(Q6)会提升步骤 3——这是唯一在你不推动之后仍能持续产生回报的工作
  • 每周小时数不足一天(Q4)会直接删除步骤 7 中的结构化项目,无论它多有吸引力

Step 1 - Baseline before changing anything

步骤 1 - 改动前先建立基线

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.
先测量,这样工作才有“之前”和“之后”,而不是两边都是观点。
  1. 运行
    scripts/contributor-path-audit.sh <repo-root>
    。它会报告社区健康文件及其显示优先级、当前文件提及十个 contributing 主题中的哪些、搭建相关面、多少 CI 工作流使用 secrets 因而无法在 fork 的 pull request 上运行,以及 git 贡献者历史——去重作者数、仅一次提交率、CHAOSS 贡献者缺席因子、每年新增作者数。
  2. 把脚本的内容探测视为词汇检查,而不是覆盖检查——它只是 grep 关键词,所以“评审期望:已提及”意味着匹配到了某个词,并不代表该主题已得到处理。在向维护者复述任何探测结果之前,先亲自读文件。
  3. 从 forge 自己的界面或 API 收集脚本看不到的数据:评分表报告格式中列出的漏斗基线数字,以及当前未被认领的新手友好 issue 数量及其年龄。响应时间使用 90 天窗口,贡献者数量使用四个季度——这两个窗口都是本 skill 自己的默认值,不是已发布的标准。
  4. 阅读最近十个来自非维护者的 pull request,按最早评论优先。记录每个 PR 在哪里停滞,以及如果存在的话,维护者的第一条回复说了什么。
  5. 如果你的环境有持久化记忆,加载该项目已存储的范围声明、响应目标或受众定义,而不是重新推导。
脚本报告的是事实,不是判断。把仅一次提交率视为基线,而不是缺陷:只有当路径修复后它仍然不动时,才成为一条发现。
使用 ./references/contributor-path-scorecard.md 对当前路径打分,并在提出改动前把结果展示给维护者。不认同诊断的维护者会拒绝治疗方案,而且他们有时是对的——你在仓库里看不到的约束,可能正说明某个被你打零分的检查是合理的。

Step 2 - Walk the path yourself

步骤 2 - 亲自走一遍路径

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.
遵循 ./references/contributor-path-scorecard.md §3 中的冷启动协议,做两轮——环境路径和任务路径——并遵守其中“搭建流程绝不能被标记为通过目视检查即工作正常”的规则。
运行期间保持一份摩擦日志:按时间戳记录每一处困惑,并为每条打上“红黄绿”严重度。对每条记录:
  • 你预期什么
  • 实际发生了什么
  • 你需要知道但没有写下来的东西
运行中途不要修复任何东西。修复会掩盖问题的真实规模。

Step 3 - Fix the environment before the prose

步骤 3 - 先修环境,再写文档

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.
描述一个坏掉搭建流程的文档比没有文档更糟,所以这一步先于任何写作。先选一个可复现层级,再填补冷启动暴露出的缺口。
三个层级,按“每单位永久维护成本所消除的搭建失败数”排序。冷启动结果在它们之间做选择:取消除实际发现失败的最高效率层级,然后停在那里。
  • 效率:
    bootstrap command > pinned toolchain > container definition
  • 价值(消除的失败):
    container definition > pinned toolchain > bootstrap command
  • 成本:
    container definition > pinned toolchain > bootstrap command
  1. Bootstrap 命令 - 一条
    make setup
    或
    ./script/bootstrap
    ,安装依赖、准备 fixtures,最后运行测试套件。一个下午即可写完,处处可用,但仍信任宿主机的工具链。
  2. 固定工具链(Pinned toolchain) - 一个宿主机工具管理器会读取的版本文件,外加一个已提交的 lockfile。以一份文件及其后续带来的升级成本,消除大多数“在我机器上是好的”报告。
  3. 容器定义(Container definition) - 一个本地编辑器和云端工作区都能使用的 development container 定义。可复现性最强,维护成本也最高:这是持续性的工作,而且当维护者自己不使用时,它也是腐化最快的层级。
  • 这个顺序会饿死什么:容器定义——它是唯一能消除整类环境失败的层级。当技术栈需要服务或痛苦的 toolchain 时(访谈问题 11),把它提前——因为在那里更便宜的层级什么也消除不了;排序永远不是交付一个无效修复的理由。
  • 根据你已知信息重新排序:一个已经在 CI 中运行容器的团队已经付过该层级的成本,这会把它单独移到该项目的效率线顶端。
在采用任何托管工作区供应商之前先采用容器定义:
.devcontainer/
格式可跨编辑器、云工作区和自托管 runner 移植,而托管选择则不可移植。供应商发布的这些工具节省时间的数据是没有同行评审测量支撑的营销数字;请阅读 ./references/published-findings.md §6 了解这一告诫,以及推荐之前需要提出的三个约束条件(谁为计算付费、先可移植后托管、漂移)。
然后按这个顺序填补缺口:
  • 让 CI 强制执行的每一项检查都能通过一条有文档的命令在本地运行。无法在本地复现红灯检查的贡献者,按定义就卡住了。
  • 把流水线拆成一条无需凭据、始终在 fork 的 pull request 上运行的通道,和一条由维护者触发的特权通道。需要 secrets 的任务无法在 fork 上运行,而且它们恰恰会把红灯展示给最需要被安抚的人。如果某个审批门禁完全卡住 fork 运行,就在文件中说明由谁批准以及多快。
  • 开启维护者对贡献者分支的编辑权限,并在文件中说明你会这样做,这样停滞的 pull request 可以被完成,而不是被关闭。
  • 说明合并风格(squash、rebase、merge commit),因为它会改变贡献者组织提交的方式。
每次修复后从干净环境重新冷启动。当不再发现新问题,这一步骤才算完成。

Step 4 - Stock the first-issue queue

步骤 4 - 充实 first-issue 队列

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.
新手标签是对辅导(mentoring)的承诺,而不是难度评级。Kubernetes 明确如此表示:他们的
good first issue
意味着成员承诺提供额外协助,而
help wanted
是更宽泛的“我们会接受补丁”。GitHub 还通过算法展示该标签,且不公布任何标准,因此这个标签会把项目之外的陌生人一并吸引进来——标签背后一个只有一行字的空 issue,会把这波注意力变成糟糕的第一印象。
  1. 停止自己修简单的 bug;每一个都是招募机会,而你却花二十分钟自己用掉了。Kent C. Dodds 在 2015 年的文章中创立了
    first-timers-only
    约定,他说明了这笔交换:“如果我直接自己做,是不是能更快搞定然后继续赶路?当然。但作为一名开源贡献者,重要的不是这个。”他的诊断正是本 skill 的根基——“第一次进入开源最难的部分不是实现一个功能,而是搞清楚如何真正贡献代码”。
  2. 写每个候选 issue 时包含七部分:观察到的行为、预期行为、相关文件及其测试、所需技能或 API、建议方法或明确的“设计尚未确定——先讨论”、确切的验证命令,以及一位具名的导师。一项 74 名参与者的研究(Steinmacher et al., arXiv:2103.12653)发现,新手会选择标注了_所需技术领域_的 issue,而不是按架构区域标注的 issue——他们问的是“我是不是已经会做这个?”,而不是“这个容易吗?”。
  3. 把每个 issue 的规模控制在从未见过代码库的人大约一个晚上能完成,包括环境搭建——这是本 skill 自己的规模默认值。修一个单词拼写错误教不了任何东西,只会产生一个再也不回来的贡献者。
  4. 明确保留非代码入口——文档、测试、triage、翻译、示例。它们是最宽的门,也是全代码队列最先丢掉的东西。
  5. 公布认领约定和过期认领的失效规则,然后执行它。一个看起来满、但全部被消失的人认领的队列,比空队列更糟。
  6. 保持至少三个有效的未认领 issue 的常备库存——这是自设的下限。一个人如果发现零个,不会以后再来看。
参见 ./references/first-issue-and-review-examples.md,其中并排展示了弱和强的 issue 正文。

Step 5 - Write the CONTRIBUTING file

步骤 5 - 编写 CONTRIBUTING 文件

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 rules while drafting:
  • Write only what is now true. Every command in the file must be one you ran in step 2 or 3.
  • Publish the response target you can actually hold, from interview question 4. A stated seven days that is met beats a stated 48 hours that is missed.
  • Put the legal gate before the reader writes code, never at the gate itself. Where the project still has the choice, a sign-off line (
    git commit -s
    ) costs a contributor nothing, while a signing workflow stops a typo fix - which is why the CNCF encourages projects to use a DCO "as it's easier to setup and use". The choice itself belongs to samber/developer-relations-skills@oss-license-strategy; only its placement in the file is yours.
  • Write for the agent reading it too: state conventions literally and near the top, write the commands out rather than only the wrapper, and keep every mandatory step inside the file rather than behind a link. The outline's §6 reads GitHub's own repo-contribution skill as the spec these three rules come from.
Place the file where the forge surfaces it and keep exactly one copy (outline §1), and link the neighbouring files instead of absorbing them (§4).
Run the finished prose through your preferred humanizer skill. A contributing guide that reads as generated undermines the welcome it extends, and this audience spots it immediately.
对照 ./references/contributing-file-outline.md 逐节起草,并在进入下一节之前获得维护者对每一节的同意。一次性重写的文件会被一次性拒绝。
起草时坚持四条规则:
  • 只写当下为真的内容。文件中的每一条命令,都必须是你已经在步骤 2 或步骤 3 中运行过的。
  • 公布你实际能守住的响应目标,来自访谈问题 4。承诺七天并做到,好过承诺 48 小时却做不到。
  • 把法律门槛放在读者写代码之前,绝不要放在提交门禁本身。在项目仍可选择的地方,一行签署说明(
    git commit -s
    )对贡献者几乎零成本,而一个签署工作流会让一个 typo 修复都停下——这正是 CNCF 鼓励项目使用 DCO 的原因,“因为它更容易设置和使用”。这个选择本身属于 samber/developer-relations-skills@oss-license-strategy;你只负责它在文件中的位置。
  • 同时为正在阅读它的 agent 而写:把约定以字面形式放在靠近顶部的位置,写出完整命令而不是只写包装脚本,并把每个强制步骤放在文件内而不是链接后面。大纲的 §6 将 GitHub 自己的 repo-contribution skill 视为这三条规则的来源规范。
把文件放在 forge 会展示的位置,并且只保留一份副本(大纲 §1);链接相邻文件,而不是把它们吸收进来(§4)。
把写好的文稿通过你偏好的 humanizer skill 处理一遍。一篇读起来像生成的贡献指南会削弱它想表达的欢迎之意,而这个受众会立刻看出来。

Step 6 - Design the review and recognition loop

步骤 6 - 设计评审与认可闭环

  1. Acknowledge on a separate clock from reviewing - the two-clock rule. A same-day "thanks, I have seen this, review by Thursday" preserves the relationship when the real review is a week out. Silence is the expensive failure, not slowness.
  2. Answer scope in the first comment. Discovering a pull request is out of scope after three review rounds is the worst outcome in the funnel for both people.
  3. Review in a fixed order: scope, then correctness and tests, then design with the reasoning attached, then style - and only the style the formatter missed. Anything a machine can fix must never appear as a human review comment.
  4. Label blocking versus optional on every comment. An unlabelled mix reads as a wall of failures.
  5. Decline fast and kindly when you must: thank them, name the scope rule, link where it was published, offer an alternative issue, close. A quick no beats a pull request rotting for six months.
  6. Credit at merge: preserve the contributor as author, name them in the release notes, and record non-code contributions somewhere the commit graph cannot - docs, triage, and design work are otherwise invisible.
  7. Invite the second contribution explicitly, with a named next issue. This is the moment a drive-by becomes a contributor, and it almost never happens on its own.
  8. Write down what happens when a pull request stalls, from both sides, and offer to finish it yourself rather than letting a bot close it.
Review against the written scope rule and that fixed order, never against an impression of the person - it is the cheapest available control on reviewer bias. Terrell et al. (PeerJ CS 3:e111, 2017) analysed 3,064,667 pull requests and found that on outside contributions - exactly the population this path serves - women's merge rate was 58% against men's 61% where gender was identifiable, while gender-neutral profiles scored highest of all. Gender was inferred and only 35.3% of users were linkable, so treat the direction as robust and the exact percentages as not; caveats in ./references/published-findings.md §5.
Turn items 1-8 into a short written playbook the maintainers actually share, and mirror the response target into the CONTRIBUTING file so contributors and maintainers read the same number. Reply templates for each situation are in ./references/first-issue-and-review-examples.md.
  1. 在独立于评审的时钟上确认收到——双时钟规则。当天一句“谢谢,我已看到,周四前评审”能在真正评审还要一周时才保住关系。沉默才是代价高昂的失败,慢不是。
  2. 在第一条评论里回答范围问题。 三轮评审之后才发现 pull request 不在范围内,是漏斗中对双方最坏的结果。
  3. 按固定顺序评审: 先范围,再正确性和测试,然后带着理由的设计,最后是风格——而且只评格式化工具漏掉的风格。任何机器能修复的内容,绝不能出现在人工评审评论里。
  4. 在每条评论上标明阻塞(blocking)还是可选(optional)。 不加标签的混合评论读起来像一堵失败之墙。
  5. 必须拒绝时要快速而友善地拒绝: 感谢对方,说出范围规则,附上规则发布处的链接,提供一个替代 issue,然后关闭。一个快速的“不”,好过 pull request 腐烂六个月。
  6. 合并时给予认可: 保留贡献者的作者身份,在发布说明中指名感谢,并在 commit 图记录不到的地方记录非代码贡献——否则文档、triage 和设计工作就不可见。
  7. 明确邀请第二次贡献,并指定下一个 issue。这是“路过”的人变成贡献者的时刻,而这几乎从不会自行发生。
  8. 写下 pull request 停滞时会发生什么,从双方角度写,并主动提出由你自己完成,而不是让机器人关闭它。
对照成文的范围规则和固定顺序进行评审,永远不要基于对个人的印象——这是控制评审偏见最便宜的手段。Terrell 等人(PeerJ CS 3:e111, 2017)分析了 3,064,667 个 pull request,发现在_外部_贡献中——正是这条路径服务的群体——在可识别性别的范围内,女性的合并率为 58%,男性为 61%,而性别中立的资料得分最高。性别是推断出来的,且只有 35.3% 的用户可关联,因此请把趋势方向视为稳健,具体百分比则不然;注意事项见 ./references/published-findings.md §5。
把 1-8 条变成一份维护者真正会分享的简短书面剧本,并把响应目标同步到 CONTRIBUTING 文件中,让贡献者和维护者看到同一个数字。每种情况的回复模板见 ./references/first-issue-and-review-examples.md。

Step 7 - Decide against the shortcuts before spending on them

步骤 7 - 在投入之前先判定捷径是否值得

Maintainers reach for a mentorship program, an onboarding event or a bot when the real problem is one of the six steps above. Each is a legitimate accelerator on a working path and a waste on a broken one, so make the call explicitly rather than by enthusiasm.
Rank them only after steps 3-6 hold: on a broken path every one scores zero whatever the ordering says. Effort means maintainer hours committed and how hard the thing is to stop once announced. Value means contributors who return.
  • efficiency:
    bot > structured program > onboarding event
  • value:
    structured program > bot > onboarding event
  • effort:
    structured program > onboarding event > bot
  • compliance cost:
    structured program > onboarding event > bot
  • A bot may absorb mechanical work, never a human moment. Leads the efficiency line on its denominator alone - an hour to install, near-zero afterwards, and reversible in one commit. Keep the first reply, the decline and the stall check-in human (step 6), and treat any wait-state a bot or approval gate introduces as a step 3 gap to document.
  • A structured program (Google Summer of Code, Outreachy, LFX Mentorship, MLH, Season of Docs) supplies the stipend and the cohort; you supply mentor hours - a standing job for a whole season, and the only item here you cannot abandon halfway without someone's summer attached to it. Host one only once steps 3 to 6 hold, because an under-mentored intern costs more than no intern. Do not promise it fixes retention: the two most-cited studies disagree, and the Mozilla analysis (Labuschagne & Holmes, MSR 2015) found contributors who started on a good-first-bug or mentored bug were less likely to become long-term contributors. Figures and caveats are in ./references/published-findings.md §3-4.
  • An onboarding event or sprint teaches mechanics well and converts nobody on its own. Last on efficiency because it costs a week of preparation plus the follow-up and buys the least measured return of the three. Kubernetes ran the field's most resourced workshop and retired it because "running the session during the summit never led to any people who weren't already contributing to the project becoming dedicated contributors". Budget the follow-up - a named next issue, an assigned mentor, a second-contribution nudge - or skip the event.
  • Delete a reward with no quality gate rather than ranking it last, and say you deleted it: it buys volume you cannot review, which is a cost, not a small benefit. Hacktoberfest's 2020 spam wave forced opt-in repositories, a longer grace period and the removal of the T-shirt entirely.
  • What this order starves: the structured program - highest value of the three, and the only one that brings people who were never going to find the project alone. Promote it when a second reviewer exists (interview question 12) and the maintainer hours in question 4 clear a mentor's weekly commitment for a full season.
  • Read the compliance line as the obligations each signs you up to:
    • a structured program: a third party's participation agreement, mentor commitments, stipend administration, and its code of conduct for a season
    • an event: a code of conduct and a venue
    • a bot: neither
    The deleted reward carries published prize rules - what Hacktoberfest had to rewrite mid-event.
  • Treat this ordering as a default, not a law: it shifts with the project and with who maintains it. Re-rank against what you know - an employer already funding mentor time, a co-maintainer who has run a cohort, an existing event to attach a sprint to - each moves an item up before the default applies.
当真实问题只是上述六步之一时,维护者会伸手去拿导师计划、上手活动或机器人。每一样在有效的路径上都是合理的加速器,在坏掉的路径上则是浪费,所以要明确做判断,而不是凭热情。
只有在步骤 3-6 成立之后再对它们排序:在坏掉的路径上,无论排序怎么说,每一样都得零分。成本指维护者投入的小时数,以及一旦公布后有多难停止。价值指会回来的贡献者。
  • 效率:
    bot > structured program > onboarding event
  • 价值:
    structured program > bot > onboarding event
  • 成本:
    structured program > onboarding event > bot
  • 合规成本:
    structured program > onboarding event > bot
  • 机器人(bot) 可以吸收机械性工作,但绝不能承担任何需要人的时刻。它仅凭分母就领跑效率线——安装一小时,之后几乎为零,一个 commit 即可回滚。让首次回复、拒绝处理、停滞检查保持人工(步骤 6);并把 bot 或审批门禁引入的任何等待状态,视为需要在步骤 3 文档化的缺口。
  • 结构化项目(structured program)(Google Summer of Code、Outreachy、LFX Mentorship、MLH、Season of Docs)提供津贴和同期学员;你提供导师时间——这是一个整季的持续性工作,也是这里唯一一个你不能半途放弃而不毁掉某人一个夏天的事项。只有在步骤 3 到 6 成立之后再举办,因为一个缺乏指导的实习生比没有实习生代价更高。不要承诺它能修复留存:引用最多的两项研究结论不一致,而 Mozilla 的分析(Labuschagne & Holmes, MSR 2015)发现,从 good-first-bug 或有人指导的 bug 开始的贡献者,成为长期贡献者的可能性_更低_。数字和注意事项见 ./references/published-findings.md §3-4。
  • 上手活动或冲刺(onboarding event or sprint) 能很好地教授操作机制,但单靠它转化不了任何人。排在效率最后,因为它要花一周准备外加后续跟进,而且是三者中测得回报最低的。Kubernetes 办了该领域资源最充足的研讨会,然后退役了它,因为“在峰会上办这个 session 从未让任何原本不在贡献的人成为深度贡献者”。为后续跟进预算资源——指定下一个 issue、分配一名导师、一次第二次贡献提醒——否则就干脆别办。
  • 对于没有质量门槛的奖励,删除它,而不是把它排在最后,并且说明你删除了它:它买到的是你无法评审的量,这是成本,不是小收益。Hacktoberfest 2020 年的 spam 浪潮迫使仓库转为 opt-in、延长了宽限期,并彻底取消了 T-shirt。
  • 这个顺序会饿死什么:结构化项目——三者中价值最高,也是唯一能把永远不会独自找到这个项目的人带进来的方式。当存在第二个评审者(访谈问题 12)、且问题 4 的维护者小时数能覆盖一个导师整季的每周承诺时,把它提前。
  • 把合规这一行理解为每一项让你承担的义务:
    • 结构化项目:第三方的参与协议、导师承诺、津贴管理,以及一季的行为准则
    • 活动:行为准则和场地
    • bot:两者都没有
    被删除的奖励带有已公布的奖品规则——也就是 Hacktoberfest 不得不在活动中途重写的东西。
  • 把这一排序视为默认值,而不是法则:它会随项目和维护者而变。根据你已知的信息重新排序——已经有雇主资助导师时间、有一位共同维护者带过同期学员、有一个现成活动可以挂靠 sprint——每一项都可以在默认值适用之前上移。

Step 8 - Re-score, then hold the target

步骤 8 - 重新评分,然后守住目标

Re-run the scorecard and iterate until it clears its threshold - all four blocking checks, plus 12 of 16 scored points. That mark is this skill's own baseline, not a published one; §4 of the scorecard has the wording to give a maintainer who asks where it comes from.
Then hold it, because the path decays - a new dependency breaks the bootstrap, the beginner queue empties, the response target slips. Re-run the audit script and one cold run every quarter - this skill's own cadence - and after any change to the build or the test command. Where your environment supports scheduled routines, install that re-check as a recurring task; where it does not, leave the maintainer a dated calendar reminder and a one-line command to re-run.
If your environment has persistent memory, store the agreed scope statement, the published response target, the beginner-issue definition, and the score with its date, so the next run measures a delta instead of starting over.
重新运行评分表并迭代,直到它越过阈值——全部四项阻塞检查,外加 16 个计分点中的 12 个。这个分数是本 skill 自己的基线,不是已发布的标准;评分表 §4 给出了向询问来源的维护者解释的措辞。
然后守住它,因为路径会腐化——新依赖会破坏 bootstrap、新手队列会空掉、响应目标会滑落。每季度重新运行一次审计脚本和一次冷启动——这是本 skill 自己的节奏——并在构建或测试命令发生任何变更之后也运行。如果你的环境支持计划任务,就把这项复检安装为周期任务;如果不支持,就给维护者留下一个带日期的日历提醒和一行可重新运行的命令。
如果你的环境有持久化记忆,存储已商定的范围声明、已公布的响应目标、新手 issue 定义,以及带日期的评分,这样下一次运行测量的是增量,而不是从头开始。

What to track afterwards

之后要追踪什么

At low volume these signals are anecdotes with dates attached, not a dashboard. Four external pull requests a quarter cannot produce a trend, and a conference talk or a front-page mention moves every number below more than a documentation change does. Record the date you shipped each change, annotate the confounders, and only then read deltas.
Track the scorecard's funnel baseline, reading each number this way:
  • New external contributors per quarter - the headline number, and the noisiest.
  • Second-contribution rate within 90 days - the retention number the whole path exists to move; the window is this skill's own default.
  • Median time to first human response, bots excluded, against the 48-hour reference point.
  • External first-pull-request merge rate and median time to merge, tracked separately from maintainers' own pull requests, which are always faster and hide the number that matters.
  • Contributor absence factor - it should rise slowly; it is the only one of these that measures whether the project got less fragile.
  • Setup support load - issues and chat messages that are really "I could not build it". A fixed path drives this to near zero, and it is the fastest-visible win.
在低流量下,这些信号只是带日期的轶事,而不是仪表盘。一个季度四个外部 pull request 产生不了趋势;一场会议演讲或首页曝光对下面每个数字的影响,都大于一次文档改动。记录你发布每项变更的日期,标注混杂因素,然后才去读增量。
追踪评分表的漏斗基线,按以下方式解读每个数字:
  • 每季度新增外部贡献者——头条数字,也是噪声最大的。
  • 90 天内第二次贡献率——整个路径存在的目的就是推动这个留存数字;窗口是本 skill 自己的默认值。
  • 首次人工回复的中位时间,排除 bot,对照 48 小时参考点。
  • 外部首次 pull request 合并率和合并中位时间,与维护者自己的 pull request 分开追踪,后者总是更快,会掩盖真正重要的数字。
  • 贡献者缺席因子——它应当缓慢上升;这是这些指标中唯一衡量项目是否变得更不脆弱的。
  • 环境搭建支持负担——那些本质上是在说“我构建不起来”的 issue 和聊天消息。一条修复好的路径会把这压到接近零,这是最快可见的胜利。

Common failure modes

常见失败模式

  • Labelling old bugs as beginner-friendly. Small for someone who knows the codebase is not small for a stranger. If it has no location, no verification command, and no mentor, it is not a first issue.
  • Optimizing recruitment while review is the bottleneck. More contributors arriving at an unstaffed review queue produces more abandoned pull requests and more resentment on both sides. Fix step 6 before promoting the project.
  • Quoting an outcome number as if it transfers. "80% of interns keep contributing" is a self-reported figure from one program's alum survey with a 37% response rate. Measure the project's own funnel, time to first response, second-contribution rate, instead of importing someone else's result.
  • Copying a large project's process. A ten-person project running Kubernetes' ladder, sponsors and rota spends its whole budget on process for contributors it does not have yet. Take the shape, not the scale.
  • 把旧 bug 标成新手友好。 对熟悉代码库的人来说小,不等于对陌生人也小。如果它没有位置、没有验证命令、没有导师,它就不是一个 first issue。
  • 在评审是瓶颈时优化招募。 更多贡献者涌向一个无人值守的评审队列,会产生更多被放弃的 pull request 和双方更多的怨气。在推广项目之前先修复步骤 6。
  • 引用一个结果数字,好像它可以迁移。 “80% 的实习生持续贡献”来自某个项目校友调查的自我报告,回收率只有 37%。去测量项目自己的漏斗、首次回复时间、第二次贡献率,而不是引入别人的结果。
  • 照搬大项目的流程。 一个十人项目去跑 Kubernetes 的成长阶梯、赞助人和轮值表,会把全部预算花在它还没有的贡献者身上。取它的形,而不是它的规模。

Reference

参考

  • ./references/contributor-path-scorecard.md - rubric, cold-run protocol, pass threshold, and report format
  • ./references/contributing-file-outline.md - section-by-section outline, volunteer-versus-corporate split, agent legibility, compact skeleton
  • ./references/first-issue-and-review-examples.md - weak and strong issue bodies, first reply, review comments, decline, merge message, stall check-in
  • ./references/published-findings.md - sources and caveats for every figure cited, plus self-set baselines
  • ./scripts/contributor-path-audit.sh - mechanical facts the scorecard depends on
  • samber/developer-relations-skills@readme-optimization - repository landing page
  • samber/developer-relations-skills@developer-quickstart-guide - user's first success with product (not contributor path)
  • samber/developer-relations-skills@oss-governance - decision rights and maintainer selection
  • samber/developer-relations-skills@developer-community-moderation - code of conduct and enforcement
  • samber/developer-relations-skills@oss-launch - attracting an audience
  • samber/developer-relations-skills@developer-journey-map - the stage this contributor path feeds
  • ./references/contributor-path-scorecard.md - 评分表、冷启动协议、通过阈值和报告格式
  • ./references/contributing-file-outline.md - 逐节大纲、志愿者 vs 公司项目差异、agent 可读性、紧凑骨架
  • ./references/first-issue-and-review-examples.md - 弱与强的 issue 正文、首次回复、评审评论、拒绝、合并消息、停滞检查
  • ./references/published-findings.md - 每个被引用数字的来源与注意事项,以及自设基线
  • ./scripts/contributor-path-audit.sh - 评分表所依赖的机械事实
  • samber/developer-relations-skills@readme-optimization - 仓库落地页
  • samber/developer-relations-skills@developer-quickstart-guide - 用户对产品的首次成功(不是贡献者路径)
  • samber/developer-relations-skills@oss-governance - 决策权与维护者选择
  • samber/developer-relations-skills@developer-community-moderation - 行为准则与执行
  • samber/developer-relations-skills@oss-launch - 吸引受众
  • samber/developer-relations-skills@developer-journey-map - 这条贡献者路径所喂给的阶段