6.5 开源贡献指南：用 PR 说话

本章目标：把”给开源项目做贡献”变成一条可执行的进阶阶梯——从改文档到核心功能。开源贡献是学生最被低估的履历资产：它同时证明工程能力、协作能力和社区声誉，且可以在面试里被验证（PR 链接挂在那，谁都看得到）。学完标准：在 30 天内完成你的第一个被合并的 PR。

1. 为什么值得（三个回报）

1. 履历硬通货：transformers/vLLM 的 merged PR 在面试中的说服力超过任何课程项目——它经过了陌生工程师的严格 review；
2. 真实工程训练：读别人的大型代码库、写规范的 commit 和测试、处理 review 意见——这些是教程永远教不了的；
3. 社区网络：review 你 PR 的人就是领域内的一线工程师——保研面试、实习内推的隐性人脉从这里来。

2. 贡献阶梯（逐级向上，每级都是真实的贡献）

级别	内容	难度/周期
① 文档/翻译	改错字、补示例、中文文档	半天/个——最佳第一步
② Issue 分诊	复现别人报的 bug、补充环境信息、确认/关闭	半天/个——练读代码
③ Bug 修复	带测试的小修复	1–3 天/个——含金量转折点
④ 新功能	先在 issue 里提案讨论，维护者点头再动手	1–2 周/个
⑤ 核心参与	长期 review 他人 PR、参与设计讨论	持续投入

选项目的原则：贡献你每天都在用的工具（LLaMA-Factory / transformers / peft / vLLM / lmms-eval——本笔记路线里的常客）。你踩过的每个 bug（7.2 案例集）都是 PR 机会：修好后顺手提 PR，“itch-driven”是最自然的贡献方式。

3. 标准流程与规范

fork → git clone 你的 fork → git checkout -b fix/xxx
→ 改动 + 补测试 → 本地过 CI（pytest/pre-commit）
→ push → 开 PR

PR 描述三段式（决定 review 速度）：What（改了什么，一行）→ Why（关联 issue #号，复现路径）→ How tested（新增测试 + 手动验证步骤）。commit 规范：小步、动词开头（fix: guard against empty batch in collator）。Review 文化：意见来了 24 小时内回应；改不动就说明理由（礼貌而坚定——和 rebuttal 同款心法，6.4）；被要求返工是常态，不是冒犯。

4. 找活干的三个入口

1. 项目 issue 区的 good first issue / help wanted 标签；
2. 维护者的 roadmap 讨论——提前认领即将要做的事；
3. 你自己的 itch：文档里过时的 API、你复现论文时发现的 bug——最有把握的贡献来源。

5. AI 协作的边界

让 agent 干：写测试样例、补文档、查 CI 失败日志的原因、把你的修复翻译成项目的代码风格。必须自己干：理解 issue 的真实意图（很多 bug 报告本身是错的）、与维护者的讨论（社区信用是人护的）、对核心逻辑修改的判断（AI 不背这个责任，你的名字背）。红线：AI 批量生成的”水 PR”（改错字刷数量）会被维护者识别并拉黑——质量文化在开源社区是真实的淘汰机制。

6. 与作品集的联动（9.3 的加层）

• GitHub profile 上 pinned 一个”开源贡献”面板（merged PR 列表）；
• 每个有分量的 PR 写一条知乎/博客（“我在 vLLM 里修了一个 KV cache 的 XX 问题”）——工程叙事的自然素材；
• 长期目标参考：一年 10 个 merged PR（3 个带测试的功能级）→ 足以支撑”具备生产级工程能力”的说法，且比任何证书都难造假。

7. 自测题

1. 贡献阶梯的”含金量转折点”在哪一级？为什么？（③带测试的 bug 修复——证明能改真实代码且守规矩）
2. 选项目的唯一正确原则？（贡献你每天在用的——有真实动机且你懂上下文）
3. PR 描述三段式为什么能决定 review 速度？（What/Why/How tested 让维护者 30 秒建立信任）
4. “itch-driven”是什么？它的优势？（修自己踩过的 bug 顺手提 PR；动机真实、上下文熟悉）
5. AI 时代开源贡献的红线？（批量水 PR——社区的质量淘汰机制会拉黑你）
6. 开源贡献对四条路（9.2）各有什么价值？（保研面试素材/复试工程证明/申请文书实例/校招简历硬通货）

8. 动手作业（30 天计划）

1. 本周：给你最常用的工具（建议 LLaMA-Factory 或 lmms-eval）通读 issue 区，挑 1 个 good first issue 认领；
2. 两周内：完成第一个 PR（文档级即可），走完 fork→test→PR→review 全流程——流程走通比改动大小重要；
3. 把 7.2 案例集里你未来踩的 bug，凡是出在开源工具里的，修一个提一个（长期机制）；
4. 建 open-source-log.md：PR 链接/状态/review 教训三列台账。

9. 延伸资源

• 《First Contributions》repo——git 协作流程的 10 分钟演练
• 各项目 CONTRIBUTING.md——LLaMA-Factory/transformers 的都是优秀范本
• OpenSource.com 的 review 文化文章——社区软技能