oss-contributor-onboarding

贡献者入门

你要修复的，是一个陌生人从想要帮忙，到提交带有自己名字的合并拉取请求之间的路径。项目会在这条路径的每一步失去参与者：

• 进入项目
• 寻找工作
• 配置环境
• 进行修改
• 提交
• 顺利通过评审
• 再次参与

找出流失发生在哪一步，修复它，并从一台干净的机器上走完整条路径，证明修复有效。

根据已发表的分类体系诊断，而不是凭直觉判断。Steinmacher 等人对新手障碍进行的系统综述（发表于《Information and Software Technology》第 59 卷，2015 年，综述了 20 项初级研究，并非对任何单个项目的测量）将记录到的所有失败归为五类：

• 社交互动
• 新手的先验知识
• 寻找入门途径
• 文档
• 技术障碍

为每项发现标明所属类别：这样可以避免审计变成一份措辞问题清单。

有两种失败最为常见，而且从项目内部看不到：

• 在维护者从未测试过的机器上，环境配置失败了，却不会产生问题报告、消息或任何痕迹。
• 对已提交的拉取请求置之不理，也会造成同样的毫无动静。

GitHub 的开源指南指出，在 48 小时内收到评审的贡献者，回归率要高得多（这是实践指导，相关数字没有已发表的数据集作为依据）；指南还指出，“一次负面体验就足以让人不想再回来”。优先解决这两种失败，再处理任何措辞问题。

只关注首次贡献路径。七个相关技能各自负责相邻的问题，并在 Reference 部分中逐项列出转接方式；如果用户真正遇到的是其中某个问题，请说明并将其转接过去。

调用方式和输出

常见调用方式，以及每种调用应产生的结果：

用户的说法	你执行	你返回
“审计首次贡献者为何放弃”	步骤 1-2，然后评分	./references/contributor-path-scorecard.md 第 5 节中的审计报告
“为这个仓库编写 CONTRIBUTING.md”	步骤 1-3，然后步骤 5	一份起草好的文件，以及证明其中每条命令都有效的冷启动运行日志
“我们的 good first issue 好几个月都无人认领”	步骤 1 基线评估，然后步骤 4	重写后的任务队列、一套认领约定和一条过期规则
“有人提交了自己的首个 PR，我不知道该怎么回复”	仅执行步骤 6	根据模板起草的回复，以及适用于下一次的双时钟规则
“我们有星标，却没有拉取请求”	完整工作流	先提供评分卡——这种说法通常指向步骤 3 或步骤 6，而不是任何文件的措辞问题

为每项交付物附上证据：

• 文件路径和行号
• 命令输出
• 带日期的统计数字

没有附带证据的建议只是意见，维护者理应对其打折看待。

访谈

每次只问一个问题，尽可能采用选择题形式，并跳过任何能通过阅读代码仓库自行回答的问题。问题 1-7 决定是否开展这项工作——回答完这些问题之前，不要起草任何文件。

记忆：记录少量有关当前任务或项目背景的信息。如果记忆存储在文件中，请使用 devrel-context.md；如果使用其他记忆系统，则依赖该系统。将任务信息分别放在不同的章节中。完成的任务要移除。为任务添加日期；一般项目背景不需要日期。有些访谈回答在两个任务之间可能不同。

1. 是哪个代码仓库？我可以阅读其中的内容并在里面运行命令吗？
2. 你真正希望增加哪方面的支持：代码贡献、文档和翻译协助、分类处理和支持协助，还是能够分担工作量的共同维护者？
3. 这是志愿维护或个人维护的项目，还是有企业支持或由基金会托管？答案会影响回复目标、法律门槛和你能承诺的贡献进阶路径——两种情况的区别见 ./references/contributing-file-outline.md §3。
4. 在普通的一周里（而不是状态最好的一周），包括审核在内，你实际每周能花多少小时处理贡献者事务？如实填写一个较小的数字，比写下愿望更有用；后续所有建议都必须以此为上限来规划。
5. 必须在什么日期之前完成这项工作——发布、资助里程碑、活动，还是没有明确期限？
6. 你希望只吸引一波贡献，还是建立一条即使你不再推动也能持续带来贡献者的路径？
7. 哪些内容不在范围内——无论写得多好，你都会拒绝哪些贡献？
8. 最近三次外部贡献尝试的结果如何？已合并、停滞、被拒绝，还是不了了之？
9. 是否存在法律门槛（DCO 签署、CLA）？贡献者是在创建拉取请求之前还是之后得知的？
10. 陌生人如今需要多久才能完成环境搭建？你上次在一台干净的机器上运行是在什么时候？
11. 你的技术栈是否会让环境搭建格外困难——例如数据库、付费 API 密钥、GPU 或专有 SDK？
12. 除你之外，还有谁能审核拉取请求？你休假时，贡献者会遇到什么情况？

如果问题 7 留空，请将其记录为审查发现的第一项，而不是阻碍。

在本技能中安排各项工作的每种顺序时，都要考虑问题 4、5 和 6，并说明各答案改变了什么：

• 截止日期临近（Q5）时，优先处理能在一个下午内完成的修复、回复目标、问题队列和首次回复，而不是需要重建的环境分级
• 需要持续积累的目标（Q6）会优先推进步骤 3；这是唯一一项在你停止推动后仍能持续产生回报的工作
• 每周可用时间少于一天（Q4）时，无论步骤 7 中的结构化计划多么有吸引力，都要彻底删除它

步骤 1——改动前建立基线

先进行测量，这样工作前后的结果就不会都是主观判断。

1. 运行 scripts/contributor-path-audit.sh <repo-root>。该脚本会报告社区健康文件及其显示优先级、当前文件提及了十项贡献主题中的哪些、设置流程、使用机密信息且因此无法在 fork 拉取请求上运行的 CI 工作流数量，以及 Git 贡献者历史数据——不同作者数、仅提交一次的作者比例、CHAOSS 贡献者缺席因子、每年的新作者数。
2. 将脚本的内容探测视为词汇检查，而非覆盖率检查——它会搜索关键词，因此“评审预期：已提及”表示匹配到了某个词，而不代表该主题已得到妥善处理。向维护者转述任何探测结果前，请先阅读文件。
3. 从代码托管平台自身的界面或 API 收集脚本无法获取的数据：评分卡报告格式中列出的漏斗基线数据，以及当前尚无人认领、适合初学者的问题数量和问题年龄。响应时间采用 90 天窗口，贡献者数量采用四个季度窗口——这两个窗口是本技能自行设定的默认值，并非已发布的标准。
4. 按评论时间从早到晚，阅读最近十个来自非维护者的拉取请求。记录每个请求在哪个环节停滞，以及维护者的第一条回复是什么（如果有）。
5. 如果你的环境具有持久记忆，请加载为该项目存储的范围声明、响应目标或受众定义，而不是重新推导。

脚本报告的是事实，而非判断。将仅提交一次的作者比例视为基线，而非缺陷：只有在修复流程后该比例仍未改善，它才会成为一项发现。

使用 ./references/contributor-path-scorecard.md 为当前流程评分，并在提出改动前向维护者展示结果。不同意诊断结果的维护者会拒绝相应的解决方案，而且他们有时是对的——仓库中不可见的限制，可能足以证明某项零分检查是合理的。

步骤 2——亲自走一遍流程

遵循 ./references/contributor-path-scorecard.md §3 中的冷启动测试流程，完成两次测试——环境流程和任务流程；并遵守其中的规则：绝不能仅凭检查就将设置标记为可用。

运行过程中记录阻碍日志：为每一次困惑标注时间戳，并为每条记录标注红黄绿严重程度。每条记录都要说明：

• 你的预期是什么
• 实际发生了什么
• 你必须知道哪些没有写明的信息

不要在测试过程中修复任何问题。修复会掩盖问题的严重程度。

步骤 3 - 先修复环境，再撰写文档

描述着一个无法正常运行的设置的文档，比没有文档更糟，所以这一步要先于任何写作。先选择一个可复现性等级，再弥补冷启动测试发现的差距。

以下三个等级按效率排序，即每单位长期维护成本能消除的设置失败数。冷启动测试决定选择哪个等级：选择能消除实际发现的问题且效率最高的等级，然后就此停下。

• 效率：bootstrap command > pinned toolchain > container definition
• 价值（消除的问题）：container definition > pinned toolchain > bootstrap command
• 投入：container definition > pinned toolchain > bootstrap command

1. 引导命令 - 一个 make setup 或 ./script/bootstrap，用于安装依赖项、准备测试夹具，并以运行测试套件结束。编写和测试需要一两个小时，适用于任何环境，但仍依赖主机上的工具链。
2. 固定工具链 - 一个主机工具管理器会读取的版本文件，以及一个纳入版本控制的锁定文件。只需一个文件及其后续带来的升级工作，就能消除大多数“在我的机器上能运行”的问题。
3. 容器定义 - 一个本地编辑器和云工作区都能使用的开发容器定义。可复现性最强，维护成本也最高：需要持续维护，而且维护者自己不用的话，这个等级最容易过时。

• 这种排序忽略了什么：容器定义是唯一能消除一整类环境问题的等级。若技术栈需要服务或难以维护的工具链（面试问题 11），就应将它提升优先级——在这种情况下，成本更低的等级什么问题也解决不了；排序绝不是发布无效修复的理由。
• 根据已知情况重新排序：如果团队已经在 CI 中运行容器，就已经承担了该等级的投入；仅对该项目而言，它便可在效率排序中位居首位。

采用容器定义后，再采用任何托管工作区供应商的服务：.devcontainer/ 格式可在不同编辑器、云工作区和可自托管运行器之间移植，而托管服务的选择则不具备这种通用性。供应商发布的此类工具节省时间数据属于营销数字，没有经过同行评审的测量支持；请阅读 ./references/published-findings.md §6，了解这一注意事项，以及建议采用此类服务前应提出的三个约束（谁支付计算费用、先考虑可移植性再考虑托管服务、偏差）。

然后按以下顺序弥补差距：

• 确保 CI 强制执行的每项检查都能通过一个有文档说明的命令在本地运行。无法在本地复现失败检查的贡献者，必然会陷入停滞。
• 将流水线拆分为两条通道：一条不需要凭据，始终在 fork 提交的拉取请求上运行；另一条需要特权，由维护者触发。需要密钥的作业无法在 fork 上运行，而且它们会对最需要安心的用户显示红色失败状态。如果审批关卡会完全阻止 fork 运行，请在文件中说明由谁审批以及审批需要多快完成。
• 启用维护者编辑贡献者分支的功能，并在文件中说明这一点，以便维护者能完成停滞的拉取请求，而不必关闭它。
• 说明合并方式（squash、rebase、merge commit），因为这会影响贡献者组织提交的方式。

每次修复后，都从干净环境重新进行冷启动测试。直到没有发现新问题，这一步才算完成。

第 4 步——储备首次贡献队列

初学者标签代表着提供指导的承诺，而不是难度评级。Kubernetes 明确说明了这一点：他们的 good first issue 意味着成员承诺提供额外帮助，而 help wanted 则是更广义的“我们愿意接受补丁”。GitHub 还会通过算法展示这个标签，却不公布任何使用标准，因此它会吸引完全来自项目之外的陌生人——如果标签背后只有一个空洞的一行问题，就会把这份关注转化为糟糕的第一印象。

1. 别再自己修复简单的 Bug；每一个都是一次招募机会，却被你花二十分钟亲自处理掉。Kent C. Dodds 的 2015 年文章催生了 first-timers-only 这一惯例，他这样阐述其中的取舍：“如果我自己动手，能更快完成并继续做别的事吗？当然能。但作为开源贡献者，重点并不在于此。”他的判断正是这项技能的出发点——“第一次参与开源时，难的不是实现功能，而是弄清楚究竟该如何贡献代码”。
2. 为每个候选问题写明以下七项：观察到的行为、预期行为、相关文件及其测试、所需技能或 API、建议的解决方式，或明确注明“设计尚未确定——请先讨论”，准确的验证命令，以及指定的导师。一项有 74 名参与者的研究（Steinmacher 等人，arXiv:2103.12653）发现，新手更愿意选择标注了_所需技术领域_的问题，而不是按架构区域标注的问题——他们想知道的是“我已经会做这个吗？”，而不是“这容易吗？”。
3. 每个问题的工作量应控制在大约一个晚上，让从未接触过代码库的人也能完成，包括环境配置——这是本技能默认的工作量标准。改一个单词的拼写错误毫无学习价值，也无法留住贡献者。
4. 明确预留非代码类的参与入口——文档、测试、问题分诊、翻译和示例。这是最宽的入口，也是全是代码的问题队列最先失去的内容。
5. 公布认领约定和认领过期规则，并严格执行。队列看起来满满当当，却全被不再活跃的人认领，比队列空着更糟。
6. 长期保留至少三个有效且未被认领的问题——这是自行设定的最低数量。一个找不到问题的人，不会过段时间再回来看看。

请参阅 ./references/first-issue-and-review-examples.md，其中并列展示了问题描述的差示例与好示例。

步骤 5 - 编写 CONTRIBUTING 文件

参照 ./references/contributing-file-outline.md 逐节起草，并在继续下一节之前征得维护者对每一节的认可。一次性改写整个文件，也会一次性被拒。

起草时牢记四条规则：

• 只写当前属实的内容。文件中的每条命令都必须是你在步骤 2 或 3 中运行过的命令。
• 公布你确实能够做到的响应时限，参照访谈问题 4。承诺七天并做到，胜过承诺 48 小时却未能做到。
• 把法律门槛放在读者编写代码之前，而不是在门槛处才提出。只要项目仍可选择，签署行（git commit -s）对贡献者来说毫无负担，而签署工作流却会阻碍一个拼写修正——这就是 CNCF 鼓励项目使用 DCO 的原因，因为「这样更容易设置和使用」。具体选择属于 samber/developer-relations-skills@oss-license-strategy；而文件中如何放置则由你决定。
• 也要为阅读指南的 Agent 而写：明确写出约定，并放在靠前位置；写出完整命令，而不只是封装命令；将所有强制步骤都写在文件中，不要藏在链接背后。大纲 §6 将 GitHub 自己的仓库贡献技能作为这三条规则的规范依据。

将文件放在代码托管平台会显示它的位置，并且只保留一份（大纲 §1）；链接到相邻文件，而不是把它们的内容并入本文件（§4）。

用你偏好的 humanizer 技能润色定稿。读起来像机器生成的贡献指南会削弱它传达的欢迎之意，而读者会立刻察觉。

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

1. 在评审之外的时间线上确认收到——双时钟规则。如果实际评审要等一周，同一天回复一句“谢谢，我看到了，会在周四前评审”，就能维护好彼此的关系。代价最大的失败不是速度慢，而是沉默。
2. **在第一条评论中说明范围。**经过三轮评审才发现拉取请求不在范围内，是对双方而言整个流程中最糟糕的结果。
3. **按固定顺序评审：**先看范围，再看正确性和测试，然后看设计并附上理由，最后看风格——而且只看格式化工具遗漏的风格问题。机器能修复的问题绝不应出现在人工评审评论中。
4. **为每条评论标明是阻塞项还是可选项。**没有标记、混杂在一起的评论读起来就像一堵失败之墙。
5. **必须拒绝时，迅速且友善地拒绝：**感谢对方，说明范围规则，链接规则的发布位置，提供一个替代议题，然后关闭拉取请求。迅速说“不”，胜过让拉取请求搁置六个月。
6. **合并时给予认可：**保留贡献者的作者身份，在发行说明中点名，并在某处记录非代码贡献——文档、问题分流和设计工作否则都会无从体现。
7. **明确邀请对方做出第二次贡献，**并指出具体的下一个议题。这是一次性贡献者成为贡献者的关键时刻，而这种转变几乎从不会自行发生。
8. **写明拉取请求停滞时双方该怎么做，**并主动提出由你完成，而不是任由机器人关闭它。

依据书面范围规则和固定顺序进行评审，绝不要凭对个人的印象来评审——这是现有成本最低的评审者偏差控制措施。Terrell 等人（PeerJ CS 3:e111，2017）分析了 3,064,667 个拉取请求，发现对于_外部_贡献——正是这条路径所服务的群体——在性别可识别的情况下，女性的合并率为 58%，男性为 61%；而性别中立的个人资料得分最高。性别是推断得出的，且只有 35.3% 的用户可以关联到性别，因此应将趋势视为可靠，而不要过度看待具体百分比；详见 ./references/published-findings.md §5。

将第 1-8 项整理成维护者实际会分享的简短书面指南，并将响应目标同步写入 CONTRIBUTING 文件，确保贡献者和维护者看到的是同一个数字。各种情形的回复模板见 ./references/first-issue-and-review-examples.md。

第 7 步——投入资源之前，先判断是否要采用这些捷径

维护者常会在真正的问题出在上述六个步骤之一时，转而求助于导师计划、入门活动或机器人。只要基础路径正常，每一种都能有效加速；但如果路径有问题，它们就只会白白耗费资源。因此，要明确作出判断，而不是凭一时热情决定。

只有在第 3 至第 6 步都站得住脚之后，才对它们排序：路径有问题时，无论排序如何，每一项的得分都是零。投入指维护者承诺投入的工时，以及公告发布后要叫停这件事有多难。价值指能再次回来的贡献者数量。

• 效率：机器人 > 结构化计划 > 入门活动

• 价值：结构化计划 > 机器人 > 入门活动

• 投入：结构化计划 > 入门活动 > 机器人

• 合规成本：结构化计划 > 入门活动 > 机器人

• 机器人可以接手机械性工作，但不能代替人与人的互动。只看投入工时，它的效率最高——安装需要一小时，之后几乎不需要投入，而且只需一次提交就能撤销。首次回复、拒绝和停滞后的跟进（第 6 步）都应由真人处理；机器人或审批关卡造成的任何等待，都应视为第 3 步的缺口并记录下来。

• 结构化计划（Google Summer of Code、Outreachy、LFX Mentorship、MLH、Season of Docs）提供津贴和项目群；你则要投入导师工时——这是一整季都要持续承担的工作，也是这里唯一不能中途放弃、否则会耽误别人整个暑期的选项。只有第 3 至第 6 步都站得住脚时，才举办这类计划，因为导师投入不足的实习生比没有实习生更糟。不要承诺它能改善留存率：引用最多的两项研究结论并不一致；Mozilla 的分析（Labuschagne & Holmes，MSR 2015）发现，从优先修复问题或导师指导的问题开始参与的贡献者，成为长期贡献者的可能性_反而更低_。相关数据和注意事项见 ./references/published-findings.md §3-4。

• 入门活动或冲刺能很好地传授操作方法，但单靠它无法转化任何人。它在效率排序中垫底，因为除了后续跟进，还要花几天准备，而三者之中它带来的可衡量回报最少。Kubernetes 曾举办过该领域资源最充足的工作坊，后来却将其取消，因为“在峰会期间举办活动，从未让任何原本没有为项目作贡献的人成为积极贡献者”。要么为后续跟进预留资源——指定下一个问题、安排导师、提醒贡献者进行第二次贡献——要么就跳过这场活动。

• 不要把没有质量门槛的奖励排在最后，而是直接删掉，并明确说明已将其删除：它带来的提交量你无力审查，这不是小小的收益，而是一项成本。Hacktoberfest 在 2020 年遭遇的垃圾提交浪潮，迫使其改为要求仓库主动选择加入、延长宽限期，并彻底取消 T 恤。

• 这种排序会让什么得不到资源：结构化计划——它在三者中价值最高，也是唯一能带来那些原本不可能独自发现该项目的人。等到有了第二位审查者（面试题 12），且问题 4 中的维护者工时足以满足导师整个季度的每周投入时，再优先考虑它。

• 合规一栏指的是每个选项会让你承担哪些义务：

  • 结构化计划：第三方的参与协议、导师承诺、津贴管理，以及整个季度都要遵守的行为准则
  • 活动：行为准则和场地
  • 机器人：两者都不需要

  被删除的奖励附带已公布的奖项规则——Hacktoberfest 曾在活动进行期间被迫重写这些规则。

• 将此排序视为默认方案，而非铁律：它会随项目和维护者而变化。根据你掌握的情况重新排序——已有雇主资助导师时间、共同维护者曾带过项目群、已有活动可附加冲刺——这些因素都会让某个选项在默认排序之前上升一位。

第 8 步 - 重新评分，然后维持目标

重新运行评分表并反复迭代，直到达到门槛：全部 4 项阻断性检查通过，且 16 个计分项中至少得 12 分。这是此技能自身设定的基准，并非已发布的标准；评分表第 4 节提供了向询问来源的维护者说明这一点的措辞。

然后持续维持这个目标，因为这条路径会逐渐失效：新依赖会破坏引导流程，新手队列会清空，响应目标会落空。每季度重新运行审计脚本并进行一次冷启动测试——这是此技能自身设定的频率；构建或测试命令发生任何更改后，也要重新运行。如果你的环境支持计划任务，就将这项复查设为定期任务；如果不支持，就给维护者留下一条注明日期的日历提醒，以及一行可用于重新运行的命令。

如果你的环境支持持久记忆，请存储已达成一致的范围说明、已公布的响应目标、新手问题的定义，以及带日期的评分，以便下次运行时衡量变化，而不是从头开始。

后续跟踪内容

在项目活动较少时，这些信号只是附带日期的个别案例，而不是仪表板数据。每季度只有 4 个外部拉取请求，无法形成趋势；一次大会演讲或首页提及，对下方每项数据的影响都大于文档更改。记录每项更改的发布时间，为混杂因素添加注释，然后再查看变化。

跟踪评分表中的漏斗基线，并按以下方式解读各项数据：

• 每季度新增外部贡献者人数 - 核心指标，也是波动最大的一项。
• 90 天内的第二次贡献率 - 整条路径旨在提升的留存指标；这个时间窗口是此技能采用的默认值。
• 首次获得人工响应的中位时间，不计机器人响应，并与 48 小时的参考值对比。
• 外部首次拉取请求的合并率和合并中位时间，与维护者自己的拉取请求分开跟踪；后者总是更快，会掩盖真正重要的数据。
• 贡献者缺席系数 - 应缓慢上升；在这些指标中，只有它能衡量项目是否变得不那么脆弱。
• 设置支持负担 - 实际上是在说“我无法构建它”的问题和聊天消息。固定路径能让这项指标接近于零，而且这是最容易快速看到成效的一项。

常见失败模式

• 把旧错误标为适合新手。 对了解代码库的人来说很简单，不代表对陌生人来说也简单。如果没有明确的位置、验证命令和指导者，它就不适合作为第一个问题。
• 在评审是瓶颈时优化招募。 更多贡献者涌入无人值守的评审队列，只会带来更多被放弃的拉取请求，也会让双方更加不满。推广项目之前，先修复第 6 步。
• 引用结果数据时，仿佛这些结果可以直接复制。 “80% 的实习生会继续贡献”是来自某个项目校友调查的自报数据，回复率为 37%。应衡量项目自身的漏斗、首次响应时间和第二次贡献率，而不是照搬别人的结果。
• 照搬大型项目的流程。 一个有 10 人的项目若照搬 Kubernetes 的贡献阶梯、赞助体系和轮值制度，就会把全部精力花在服务尚不存在的贡献者上。借鉴其模式，而不是照搬其规模。

参考资料

• ./references/contributor-path-scorecard.md - 评分标准、冷启动测试流程、通过门槛和报告格式
• ./references/contributing-file-outline.md - 分章节大纲、志愿者与企业的内容划分、对 Agent 的可读性、精简骨架
• ./references/first-issue-and-review-examples.md - 弱与强的问题正文、首次回复、评审评论、拒绝、合并消息、停滞跟进
• ./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 - 该贡献者路径所衔接的阶段