AI-Infra 开源贡献指南

1

AI-Infra 开源贡献指南
系列精华 · 读懂 → 找到 → 做出 → 两个真实 PR，以 PyTorch 与 vLLM 为例

arganzheng · 2026-10-04

这个系列的一句话主张

maintainer 的 review 时间是项目最稀缺的资源，所有规则都是为了保护它；细节会变，这条逻辑不变——理解了它就能在规则变化后自己推导出新的做法。

	PyTorch	vLLM
历史	十年、治理成熟	两年、规则快速演化
发布	约 2 个月	约 2 周
CI	全跑、bot 合入	按需跑（`/ci run`）、maintainer 手动合入
门槛	2000 行硬上限、33 条 merge rule	6 个 open PR 上限、DCO 每个 commit

四篇按一次贡献的自然顺序：读懂 → 找到 → 做出 → 看两个完整实例。

四篇怎么连起来

%%{init: {"flowchart": {"wrappingWidth": 420}}}%%
flowchart TB
    C1["01 读懂一个百万行代码库：地图、入口、生成代码、构建、测试、历史"] --> C2["02 找到切入点：标签、RFC、CI 失败、性能回归；先讨论、查重"]
    C2 --> C3["03 做出能被合入的改动：最小 diff、测试、lint、描述、CI、review"]
    C3 --> C4["04 两个真实 PR 的走读：PyTorch #185344 · vLLM #47272——前三篇的规则在时间线上各出现在哪"]

01 · 读懂一个百万行的代码库：两小时定位到一个函数

结论：靠有目标的检索——提取符号 → 画地图 → rg → 找登记表 → 沿链追 → 识别生成代码 → 读测试 → 读历史；构建是为了工具链，可选、放最后。

	PyTorch	vLLM
地图（依赖只向下）	`c10/` → `aten/` → `torch/csrc/` → `torch/`	`csrc/` → `vllm/`
登记表	`native_functions.yaml`	`pyproject.toml` / `torch_bindings.cpp`
生成代码	`ATen/ops/*.h`、`.pyi` 由 `torchgen` 生成	`torch.ops._C.<op>` 在 `.so` 里

引言案例：四十分钟得出「已在 v2.11.0 修复」
「rg 找不到 def、头文件不存在，说明仓库不完整」——是生成代码；回登记表

02 · 找到切入点：maintainer 最希望有人做的是哪类

结论：他们已决定要做、写清了要什么、自己没时间做的事；预测「一周后会不会被关」看六个信号：标签状态、maintainer 最后一条评论、open PR 数、规模与 RFC 门槛、硬件、项目政策。

信号	PyTorch	vLLM
标签	682 个，`actionable` 396 占不到 3%；状态链四态	63 个；`closed-as-slop` 已打在 97 个 PR 上
RFC 门槛	设计决策	> 500 LOC（不含 kernel / data / config / test）
stale	90 + 30 天
查重	#191394 下挂着 5 个 open PR

「issue 还 open 就是没人在做」——三条查重命令看 open PR 数与最后一条评论；good first issue 是最挤的池子
「typo PR 是最安全的第一个 PR」——vLLM 明文不接受 busywork；做成有范围、有依据、能说出「怎么找全」的 systematic 批次

03 · 做出一个能被合入的改动：reviewer 十分钟要确认四件事

结论：改了什么且只改了这一件（diff）、为什么改怎么验证（描述）、怎么证明对怎么防回归（测试）、有没有弄坏别的（CI）——四样各答一个问题。

	PyTorch	vLLM
大小	2000 行硬上限	6 个 open PR 上限
lint	61 个 linter	pre-commit；需 `verified` / `ready` 或 ≥ 4 个合入 PR 才自动跑
CI	148 个 workflow、49 个 `ciflow/*`、33 条 merge rule	35 个 test_area；测试任务要 `/ci run`，新 commit 不自动重跑
催	4 个工作日	2–3 天 / 7 天
签名	CLA	DCO 每个 commit

「vLLM 的 PR 开出来 CI 是灰的，等它自己跑」——本地 pre-commit run --all-files；等 reviewer 敲 /ci run；每次 push 后重新敲

04 · 两个真实 PR：时间花在哪里

结论：小 PR 的时间不在写代码——PyTorch 那个在数据（正常成本），vLLM 那个在等待（大半可省）。

	PyTorch #185344	vLLM #47272
diff	+104 −0	+109 −16
时间线	27 天采 3792 个点 → PR 5 天	47 天无 review、未 ping
review	3 小时 42 分收到；三条意见全是注释与来源	6 个自己引入的 CI 失败
合入	`merge -i`，进 v2.13.0	合入 08-20，不在 v0.28.0（分支 08-17 切出）

「review 意见是在检查算法对不对」——提交前用描述里的数字校对代码注释；署名放描述不放代码
「合入了就在最新版里」——git tag --contains <sha>；merge-base --is-ancestor 核对

一条贯穿线：每条规则保护的是 review 时间

规则	省了 reviewer 什么
先讨论、查重	不 review 一个会被关的 PR
RFC 门槛	设计决策一次拍板，不在 diff 里反复
最小 diff、一件事	十分钟能看完
描述写数字与验证方法	不用自己复现
测试 + lint 本地过	不当人肉 CI
`/ci run` 门槛、6 个 open PR 上限	CI 机器时间也是 review 时间
不接受 busywork、`closed-as-slop`	不 review 没有价值的改动

9
常见误区
- 「rg 找不到 def 说明仓库不完整」——生成代码，回登记表
- 「issue 还 open 就是没人在做」——看 open PR 数
- 「代码写得多就要 RFC」——标准是有没有设计决策
- 「typo PR 最安全」——vLLM 不接受 busywork
- 「vLLM 的 CI 会自己跑」——要 /ci run
- 「review 是在检查算法」——多半是注释、来源、范围
- 「合入了就在最新版里」——看分支切出时间

四个出口

篇	一个判据
01	地图 + 登记表 + `rg`；构建放最后
02	已决定、写清了、没时间；六个预测信号
03	diff / 描述 / 测试 / CI 各答一个问题
04	数据是正常成本，等待可省——ping

11
下一步
- 往下：《C++ 在 AI-Infra》第 8 篇、《ML 编译器》第 13 篇——工具链与工作台
- 往旁：《PyTorch 深度实践》第 10 篇——被贡献的那个工程体系长什么样；《vLLM 源码》——被贡献的那个引擎
- 原文总纲：/contributing-to-ai-infra-open-source.html；通关自测在系列总结

这篇对你有用？

COMMENTS

评论存放在 GitHub Discussions，用 GitHub 账号登录即可发表，支持 Markdown。想针对正文某句话说？选中那段文字，点浮出的「评论」即可划线评论；觉得哪里写错了，发表时勾上「同时提交 Issue」。有人回复你时 GitHub 会按你的通知设置发邮件，不用守在这里。