ESLint 维护者指南:Pull Request 审查、审批与合并全流程解析
ESLint 维护者指南:Pull Request 审查、审批与合并全流程解析
导读
本文基于 ESLint 官方维护文档 review-pull-requests.md,系统讲解 ESLint 项目中 Pull Request(PR)从提交、机器人检查、人工审查、分级审批、Triage 看板流转到最终合并或关闭的完整治理流程。无论你是希望了解大型开源项目如何把控代码质量的新贡献者,还是准备参与 ESLint 维护工作的团队候选人,读完本文都能掌握:机器人自动检查的职责边界、审查者应逐项核对的内容清单、不同变更类型对应的审批门槛、合并等待期规则,以及何时应该关闭一个 PR 并如何给出恰当的关闭评论。
为什么需要一套严格的 PR 审查流程
Pull Request 是 ESLint 社区贡献者提交代码的主要途径,也是项目团队与社区互动的最佳机会。正如 pull-requests.md 所述,ESLint 明确要求所有代码以 PR 形式提交——不要用 Issue 贴代码片段,因为那会迫使维护者手动合并代码并补齐测试,降低代码被采纳的概率。
在 review-pull-requests.md 开头,官方给出了两条核心立场:
- PR 提交频繁,是团队与社区互动的第一现场,因此合并前必须经过充分审查;
- PR 上的互动必须是积极、友好的,审查意见应当建设性而非对抗性。
这两条原则贯穿整个流程:审查严格但语气温和,机器人承担机械性检查,人工专注于代码质量、约定符合度与变更合理性。
谁可以审查 Pull Request
任何人都可以在 PR 上留言评论——无论是团队成员还是普通公众。这是 ESLint 开放治理的体现:公众的反馈同样被认真对待,但审批(approve)与合并(merge)权限则严格分级。
从 governance.md 可以看出 ESLint 的角色体系:User(用户)→ Contributor(贡献者)→ Committer(提交者)→ Reviewer(评审者)→ TSC(技术指导委员会)成员,另有独立的 Website Team Member(网站团队成员)负责 eslint.org 仓库维护。各角色职责不同,PR 审查正是这些角色协同工作的核心场景。
机器人自动检查:打开 PR 后的第一道关卡
当一个 PR 被打开时,机器人(bot)会立即执行三项检查:
- 提交者是否签署了 CLA(贡献者许可协议)——未签署 CLA 的代码无法被合法合并;
- commit message 摘要格式是否正确——ESLint 遵循 Conventional Commits 规范(详见 pull-requests.md,注意 ESLint 不支持可选的 scope 部分);
- commit 摘要是否过长——摘要必须是一句话且不超过 72 个字符。
机器人会把发现的问题以评论形式贴到 PR 上。官方文档特别提醒:在机器人指出的问题被解决之前,不需要再进一步查看这个 PR,也无需重复评论催促提交者——那是机器人存在的意义。这条规则避免了团队成员的重复劳动,也让贡献者明确知道下一步该做什么。
关于 commit message 的格式,pull-requests.md 给出了更详细的 tag 清单,审查时可以对照核对:
| Tag | 含义 |
|---|---|
fix |
缺陷修复 |
feat |
向后兼容的增强,或会新增上报问题的规则变更 |
fix! |
不向后兼容的缺陷修复 |
feat! |
不向后兼容的增强或特性 |
docs |
仅文档变更 |
chore |
不面向用户的变更 |
build |
仅构建过程变更 |
refactor |
不影响 API 或用户体验的重构 |
test |
仅测试文件变更 |
ci |
CI 配置与脚本变更 |
perf |
提升性能的代码变更 |
PR 标题由首个 commit 的摘要自动生成,因此 commit 摘要格式的检查本质上就是在把关 PR 标题——而 PR 标题又会被用于生成每次发布的 changelog,这也是格式如此重要的原因。
人工审查清单:机器人通过之后该检查什么
机器人检查全部通过后,审查者需要逐项人工核验:
- 核对 PR 标题:根据关联的 Issue(若无关联 Issue,则根据 PR 陈述的问题)判断标题是否正确。
- 核心代码变更必须有关联 Issue:如果 PR 修改了 core(核心代码),确保存在对应 Issue,且 PR 在 commit message 中引用了该 Issue。
- 代码是否符合项目约定:包括头部注释、JSDoc 注释等。若不符,应在反馈中引用 Code Conventions 文档。ESLint 的代码约定由 eslint-config-eslint 决定,涉及
package.json的修改还需参考 package-json-conventions.md。 - 针对代码变更:
- 是否有验证变更的测试?没有则要求补充;
- 变更是否需要文档?需要则要求提交者补充文档。
- 自动化测试是否有错误:若有,请提交者检查处理。
- 给出结论:若审查完毕且无遗留问题,评论
LGTM表示批准;若希望其他人再核验,评论LGTM but would like someone else to verify.。
特别提醒(针对团队成员):如果你在 PR 上留下了评论,请跟进确认你的意见已被处理。不能"评论完就消失"——跟进闭环是团队责任的一部分。
关于测试的硬性要求
review-pull-requests.md 要求"任何变更都必须有测试",这一点在 tests.md 中有具体支撑:ESLint 的单测基于 Mocha 编写,全部位于 tests 目录,提交前必须运行:
npm test
从 Makefile.js 的 target.test 可以看到,npm test 实际包含:checkRuleFiles()(校验规则文件)、Mocha 单元测试、150 次 fuzzing 测试以及许可证检查;而 target.mocha(Makefile.js)使用 --forbid-only 防止 only 测试混入完整测试运行,并要求语句覆盖率 99%、分支覆盖率 98% 的硬指标(c8 check-coverage --statements 99 --branches 98 --functions 99 --lines 99)。这意味着审查者完全可以信任"测试已通过"的 CI 状态背后有一套严格的阈值约束。
分级审批:不同变更需要不同的批准门槛
任何 committer、reviewer 或 TSC 成员都可以批准(approve)一个 PR,但合并所需的批准数量取决于 PR 类型:
非破坏性变更(Non-breaking Change)——1 个 committer 批准即可
适用于以下五类:
- 文档变更(documentation change)
- 缺陷修复(bug fix,针对规则或核心代码均可)
- 依赖升级(dependency upgrade)
- 构建相关(build)
- 杂务(chore)
非破坏性特性(Non-breaking Feature)——2 级批准
需要 1 个 reviewer 或 TSC 成员批准 + 另外 1 个任意团队成员批准。特性涉及 API 或行为的新增,双人核验降低回归风险。
破坏性变更(Breaking Change)——2 个 TSC 成员批准
破坏性变更直接影响用户升级路径(对应 semver 的 major 版本),门槛最高。这与 manage-releases.md 中"破坏性变更并入 main 分支、随主版本发布"的策略一致,也与 manage-issues.md 中"破坏性变更应打上 breaking 标签"的要求呼应。
批准后不合并的规范
::: important 如果你批准了一个 PR 却没有合并它,请务必留下评论解释原因。例如:
LGTM. Waiting three days before merging.(等待三天再合并)LGTM. Requires TSC member approval before merging.(还需 TSC 成员批准)LGTM. Would like another review before merging.(希望再多一位审查) :::
这条规则保证了审批与合并两个动作之间的信息透明,任何团队成员都能从评论中理解 PR 的当前状态。
Triage 看板:PR 的状态流转
ESLint 所有仓库的 Issue 和 PR 都在 Triage Project 看板上管理(相关列定义详见 manage-issues.md)。PR 创建后(无论来自团队成员还是外部贡献者)自动进入 "Needs Triage" 列,应保持在该列直到有团队成员开始审查。
根据是否关联 Issue 决定走向
- 无关联 Issue:按 manage-issues.md 的常规 triage 流程处理,标记为 accepted 后移入 "Implementing" 列。
- 有关联 Issue:
- Issue 已 accepted → 直接移入 "Implementing" 列;
- Issue 未被 accepted → 移入 "Evaluating" 列,待 Issue 被 accepted 后再移到 "Implementing"。
获得第一个批准后的三种分支
PR 获得一个批准后,视情况走三条路:
- 已达所需批准数且等待期已过 → 可以合并;
- 已达所需批准数但等待期未过 → 移入 "Merge Candidates" 列;
- 还缺其他批准 → 移入 "Second Review Needed" 列。
当 PR 获得第二个批准时:若 100% 就绪则直接合并;若仍有应在下个版本发布前复核的遗留问题,则移入 "Merge Candidates" 列(该列 PR 的特征是:至少有一个批准、且至少一位批准者认为可以在下个版本合并,但仍希望 TSC 成员核验)。
谁可以合并 PR
TSC 成员、reviewer、committer 以及 website team members 在获得所需批准后,根据 PR 内容决定是否可以合并。
特别地,Website Team Members 仅在以下三种情况下可合并 eslint.org 仓库的 PR:
- 文档变更
- 依赖升级
- 杂务
这与其角色定位一致——网站团队成员聚焦 eslint.org 的内容维护,不触碰核心代码合并权限(详见 governance.md)。
何时合并:合并前置条件与等待期
ESLint 使用 GitHub 的 "Merge" 按钮将 PR 合入仓库。合并前必须逐项确认:
- 所有评论都已处理;
- 发表过评论的团队成员已确认自己的关切被解决;
- 所有自动化测试通过——绝不合并测试失败的 PR。
合并前不要忘记向提交者道谢,尤其是当对方为这个 PR 付出了大量工作时。
可以立即合并的情况
满足以下任意一条,团队成员可以立即合并:
- 小型的文档变更;
- 杂务(chore);
- 修复仓库中其他工作阻塞(构建相关、测试相关、依赖相关等);
- 需要进入 patch 版本的重要修复。
等待期规则
其余情况应遵守等待期,给其他团队成员留出审查机会:
- PR 在周一至周五打开 → 等待 2 天;
- PR 在周六或周日打开 → 等待 3 天。
(等待期与 Issue 关闭的等待期规则完全一致,见 manage-issues.md。)
注意:未获得所需批准前,不要合并自己的 PR。
等待期机制与 manage-releases.md 描述的发布节奏配合:周五发布新版本、周一评估是否需要 patch 版本,等待期确保任何变更在进入下一个版本前都有充分的多人检视窗口。
何时关闭 PR:不合并就关掉,但要说明理由
在以下三种情况下,可以关闭 PR 而不合并:
- PR 解决的 Issue 已经被修复(重复劳动);
- PR 已经 17 天没有更新(贡献者失去兴趣或放弃);
- PR 提交者不愿意遵循项目指南(合作意愿问题)。
在任何关闭情况下,都必须留下评论说明关闭原因——这是对贡献者劳动的基本尊重,也让流程可追溯。
官方示例关闭评论
17 天无更新时:
Closing because there hasn't been activity for 17 days. If you're still interested in submitting this code, please feel free to resubmit.
(关闭原因是没有活动 17 天;如果你仍感兴趣,欢迎重新提交。)
提交者不愿遵循项目指南时:
Unfortunately, we can't accept pull requests that don't follow our guidelines. I'm going to close this pull request now, but if you'd like to resubmit following our guidelines, we'll be happy to review.
(很遗憾,我们无法接受不遵循指南的 PR;我现在关闭它,若你愿意按指南重新提交,我们很乐意审查。)
两则评论的共同点是:陈述事实 + 给出重新提交的出路。这与 manage-issues.md 中"Issue 可以随时重开"的宽松关闭哲学一脉相承——关闭不等于终结,而是保留重新激活的可能性。
与社区互动的心态准则
虽然 review-pull-requests.md 聚焦流程本身,但其开篇"PR 上的互动必须是积极的"这一要求,与 manage-issues.md 的 "Things to Keep in Mind" 高度一致,值得审查者在实践中落实:
- Be nice(友善):即使对方无礼,团队成员也必须成熟克制;措辞不佳可能只是贡献者英语不熟练,不要急于断定恶意;
- Be inquisitive(好奇追问):信息不完整时主动提问,不要自行脑补;
- Not all requests are equal(并非所有请求都同等重要):敢于说明某些变更不在项目范围内;
- Close when appropriate(适时关闭):确定没有后续工作的 PR 可以关闭,但务必留下说明。
结语:把"社区互动"与"代码质量"同时管好
回顾整套流程,ESLint 的 PR 治理呈现出清晰的分层设计:机器人接管机械性的格式与 CLA 检查,解放人工;人工审查聚焦代码质量、测试完备性与文档配套;分级审批根据破坏性程度匹配不同数量的批准者;等待期 + Triage 看板保障多人检视与状态透明;关闭准则则让无法合并的 PR 也能体面收场。这种"严格但不冷酷"的流程,正是 ESLint 能够在十多年间保持高代码质量与活跃社区的原因之一。
对于想要进一步了解完整维护体系的读者,建议继续阅读同目录下的 manage-issues.md(Issue 与 PR 的 triage 全流程)、manage-releases.md(发布与版本管理),以及贡献侧的 pull-requests.md(从贡献者视角理解提交规范)与 governance.md(角色与权限体系)。