Electron 仓库 Pull Request 完整指南：从环境搭建到代码合入的 11 步贡献流程

Electron 是一个由 Chromium、Node.js 与 C/C++ 深度绑定构成的复杂跨平台桌面应用框架，想要为 electron/electron 仓库贡献代码，遵循一套严格的 Git 协作与代码评审流程必不可少。本文以仓库 docs/development/pull-requests.md 的贡献指南为主线，完整拆解从 Fork、本地构建、编写提交、跑测试到最终合入（Landing）的每一步，并结合仓库内的源码与配置（如 package.json、script/spec-runner.js、spec/index.js、.github/PULL_REQUEST_TEMPLATE.md）补充底层机制，帮助读者提交一份规范、可评审、能顺利合入的 Pull Request。

一、为什么 Electron 的 PR 流程比普通仓库更复杂

electron/electron 并不是一个"克隆后即可开写"的普通仓库。它同时捆绑了 Chromium、Node.js、V8 等巨型上游项目，仓库采用嵌套仓库（nested repository）结构，Electron 本体只是整个源码树中的一个子目录。这一点在开发文档 docs/development/README.md 中亦有说明：Electron 构建在 Chromium 和 Node.js 之上，二者的部分功能还需通过 patches/ 目录下的补丁方式维护。

因此，向 Electron 提 PR 之前，必须先通过官方构建工具链把项目完整编译出来；同时，由于改动会跨越 C/C++（shell/）、TypeScript（lib/）、文档（docs/）与测试（spec/）等语言和目录，仓库对提交信息（semantic commit）、代码风格、测试与评审批准也都有硬性要求。下文即按官方指南的 11 个步骤逐一展开。

二、环境准备：Fork、构建与本地方分支

Step 1：Fork 仓库

首先在托管平台上 Fork electron/electron 官方仓库到自己的账号下，为后续推送个人分支做准备。

Step 2：使用 @electron/build-tools 完成构建

Electron 官方建议使用 @electron/build-tools 工具链来构建 Electron 本身，而不是手动逐个同步子仓库。整个过程只需两条命令：

# 全局安装 build-tools 包：
npm install -g @electron/build-tools
# 在你想克隆项目的位置执行 init 脚本，并指向你的 fork：
e init --fork my-org/electron --bootstrap testing

执行完成后，工具会在当前工作目录创建一个新的 electron 文件夹并初始化项目。注意： 你的 fork 实际上被克隆在 electron/src/electron 这一层目录中——这正是前文所说的嵌套仓库结构，上游的 Chromium/Node.js 源码位于 src/ 下，Electron 自身代码在 src/electron 中。

[!IMPORTANT] 由于 Electron 项目结构复杂且包含多层嵌套仓库，建议阅读构建说明文档 docs/development/build-instructions-gn.md，了解 @electron/build-tools 的详细用法（例如如何同步依赖、如何重新编译二进制文件）以及各平台的专属注意事项。

构建成功后，在 src/electron 内会配置两个 git remote：

• origin 指向官方的 electron/electron；
• fork 指向你自己的 fork（如 my-org/electron）。

以 fork 作为推送目标、origin 作为同步上游，可以在后续流程中避免污染主仓库的追踪分支。

Step 3：从 main 切出工作分支

为保证开发环境整洁，工作应放在独立本地分支中，且必须直接从 main 分支切出：

git checkout -b my-branch

三、编码、提交与消息规范

Step 4：明确改动落点并遵守代码风格

面向 electron/electron 的 PR 通常改动以下四类位置之一：

• shell/ 下的 C/C++/Objective-C++ 代码——Electron 的底层原生实现，例如浏览器主进程功能；
• lib/ 下的 TypeScript/JavaScript 代码——Electron 对外暴露的上层 API 封装；
• docs/（尤其是 docs/api/）下的文档；
• spec/ 下的测试用例。

编码过程中应随时运行 yarn lint，确保改动符合项目代码风格。从根目录 package.json 可以看出，lint 是一条组合脚本，依次执行 script/lint.js、格式检查 lint:fmt（使用 oxfmt 校验 lib/、spec/、script/ 等目录的 JS/TS）、文档检查 lint:docs 与 Chromium roller 检查 lint:chromium-roller；其中 lint:docs 又细分为 Markdown 内 JS 代码检查、TypeScript 定义生成、相对链接校验等多道工序。对于 shell/ 的 C++ 改动，仓库还提供了 lint:clang-format（调用 script/run-clang-format.py）与 lint:clang-tidy 等专项检查。

不同目录的代码遵循不同的最佳实践，详见仓库的编码风格文档。

Step 5：提交（Commit）与签名

官方建议将改动按逻辑分组成多个提交，而不是一次大提交；一个 PR 中的提交数量没有上限，且合入时会被自动压缩（squash）成单个提交：

git add my/changed/files
git commit

提交签名：硬性要求

electron/electron 对所有传入的 PR 强制要求提交签名（commit signature）。请先在 Git 中配置好用于提交签名的 GPG/SSH 密钥，确保每条提交都带有可信签名，否则 PR 会因验证失败而无法被合入流程接收。

提交消息规范：语义化前缀

Electron 使用 semantic commit messages 风格来梳理发布流程。在 PR 合入之前，PR 标题必须带有语义前缀。官方给出的示例与常见前缀包括：

前缀	含义
fix:	缺陷修复
feat:	新功能
docs:	文档变更
test:	补充缺失测试或修正现有测试
build:	影响构建系统的改动
ci:	CI 配置文件与脚本的改动
perf:	提升性能的代码改动
refactor:	既不修 bug 也不加功能的代码重构
style:	不影响代码含义的格式调整（如 linting）

官方示例（真实历史风格）：

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

除此之外，提交消息正文还需满足：

1. 首行：包含简短变更描述，建议不超过 50 字符（上限 72 字符）；除专有名词、缩写以及函数/变量名等代码引用外，全部使用小写；
2. 第二行留空；
3. 其余行在 72 列处换行。

Breaking Changes 标记

如果提交在可选正文（body）或页脚（footer）的开头包含 BREAKING CHANGE: 文本，即表示引入破坏性 API 变更，这与语义化版本中的 Major 版本对应。破坏性变更可以出现在任意类型的前缀中，fix:、feat: 甚至 chore: 均合法。

Step 6：Rebase 同步上游（而非 merge）

提交完成后，推荐使用 git rebase（而不是 git merge）将工作分支与主仓库同步，确保基于最新的 electron/electron main 分支：

git fetch origin
git rebase origin/main

Step 7：测试：bug 修复与新功能必须携带用例

缺陷修复和功能改动必须配套测试。仓库提供了完整的测试指南帮助编写用例，也可以参考现有测试了解结构。提交 PR 前应始终运行完整测试套件：

yarn test

务必保证 linter 无报告、所有测试通过，不要提交两者任一失败的补丁。

如果只想针对某个模块运行单个 spec（适合处于测试链路末端的用例作者），使用 -match 过滤：

yarn test -match=menu

上述命令只会运行与 menu 匹配的 spec 模块。这条命令在仓库源码中可以得到印证：spec/index.js 通过 process.env.npm_config_match 读取该参数并构造 RegExp 来筛选模块文件，同时命令行入口 yarn test 实际调用的是 script/spec-runner.js（见 package.json 中 "test": "node ./script/spec-runner.js"）。也就是说，根目录 yarn test 会先处理 Electron 二进制准备与依赖安装等前置逻辑，再把未知参数透传给 spec 层按模块名过滤，最终调用真正的 Electron 可执行文件运行 Mocha spec。

Step 8：推送工作分支到 fork

当测试与 lint 全部通过后，把工作分支推送到自己的 fork 以发起 PR：

git push fork my-branch

四、发起 PR、评审沟通与合入

Step 9：按模板填写 PR 描述

在托管平台打开 Pull Request 时，仓库提供了必须填写的模板，即 .github/PULL_REQUEST_TEMPLATE.md。模板要求提交者完成 Checklist，包括但不限于：

• 已构建并测试本次改动；
• 已填写 PR 描述；
• npm test 通过；
• 依据测试指南新增或修改了测试；
• 相关的 API 文档、教程与示例已同步更新并遵循文档风格；
• Release Notes 中关于本次改动的描述对应用开发者可读，且使用恰当的时态、大小写与标点。

如果模板填写不充分，维护者会因需要补充信息而推迟合入，因此建议一次填写完整。

Step 10：评审讨论与"Approval / Request Changes"工作流

PR 提交后大概率会收到反馈或变更请求，这是提交流程的重要组成部分。收到意见后，在本地分支继续修改、追加新提交并再次推送，GitHub 会自动更新该 PR：

git add my/changed/files
git commit
git push fork my-branch

值得说明的两点协作约定：

• 若在等待某问题的答复，可以在 PR 中留言 @ 评审者提醒；
• 遇到陌生的术语或缩写，可参考 Chromium 术语表。

审批与"请求变更"工作流

在评审维度上，所有 PR 都需要所改动区域的 Code Owner 批准才能合入。仓库根目录的 .github/CODEOWNERS 定义了各路径的负责人与工作小组，例如 patches/ 归 @electron/patch-owners、DEPS 归 Upgrades WG、npm/ 与发布相关目录归 Releases WG、若干与安全相关的 lib/ 文件归 Security WG。规则采用 gitignore 风格且靠后匹配优先。

维护者在评审时可以请求变更（Request Changes），有些只是修个错别字的小请求，有些则涉及实质性改动。官方文档特意提醒贡献者不要因此气馁：若觉得评审不公，可以在 PR 中说明或寻求其他贡献者的意见；多数情况下此类评论只是评审者投入时间不足所致，而并非恶意。当然，评审者本身也应被期待提供有建设性的反馈。

Step 11：Landing（合入）

PR 合入需要同时满足两个条件：至少一位对应区域的 Electron Code Owner 评审通过，并且 CI 全部通过。若没有其他贡献者提出异议，即可被合并。

持续集成（CI）测试：所有平台跑绿

每一个 PR 都会在 CI 系统上针对 Electron 支持的全平台运行测试，以确认改动在各平台均可工作。理想情况下 PR 应在所有平台"全绿"（所有测试通过且无 lint 错误）。但 CI 基础设施本身偶尔会在特定平台失败，或出现所谓的 "flaky"（不稳定）测试变红。每一次 CI 失败都需人工检查以确定根因，因为失败可能来自：

1. 改动本身引入的真实回归；
2. CI 基础设施的平台性故障；
3. 偶发的 flaky 测试。

值得注意的是：PR 一打开 CI 就会自动启动，但只有核心维护者可以重启 CI 运行。如果你确信 CI 属于误报（false negative），可以请维护者重启测试。

五、提 PR 前的全局视角：从根目录看测试与贡献全景

如果准备动手提 PR，以下几条来自仓库内部的补充信息有助于提升一次通过率：

• 目录职责：整体结构概览可参考 docs/development/source-code-directory-structure.md；其中 shell/ 下按 app、browser、common、renderer 等分层存放原生代码，例如 shell/app、shell/browser 拥有数百个 .cc/.h 文件。
• spec 体系：spec/ 下文件名与 API 一一对应（如 api-menu-spec.ts、api-web-contents-spec.ts），提交 API 类改动时可找到对应 spec 补充用例。
• lint 一站式入口：根目录 package.json 中的 precommit（lint-staged）会在提交时对不同类型的文件自动执行对应的格式化与检查，例如 *.{cc,mm,c,h} 走 clang-format、*.{js,ts} 走 oxfmt 与 lint、docs/api/**/*.md 走 markdownlint 并自动更新 filenames.auto.gni。提前在本地让 lint-staged 全绿，可避免在 CI 环节反复返工。
• 依赖与补丁的边界：官方在 CONTRIBUTING.md 中明确，package.json 与 yarn.lock 的依赖变更只允许维护者提交（出于安全原因不接受外部 PR）；涉及 Chromium/Node.js 上游的改动则走 docs/development/patches.md 描述的打补丁流程，此时 PR 中需要包含对 patches/ 目录的修改。
• AI 工具政策：若在贡献过程中以任何形式使用了 AI 工具，请遵循 CONTRIBUTING.md 中列出的 AI Tool Policy——核心原则是"必须有真人参与闭环（human in the loop）"：贡献者需亲自审查、理解并能解释自己的改动，未经人工复核的 AI 生成内容会被婉拒。
• 开发总览：PR 之外的问题提报、补丁管理、调试等完整开发文档可从 docs/development/README.md 进入。

六、小结：一份可合入 PR 的检查清单

综合官方指南与仓库配置，可把"提交到 electron/electron"收敛为如下自检清单：

1. 基于最新 main 切出独立分支，改动聚焦单一逻辑主题；
2. 在本地完成构建，yarn lint 无报错，yarn test（或 yarn test -match=xxx 定向验证）全部通过；
3. 提交均带有效签名，PR 标题带 fix:/feat:/docs: 等语义前缀，正文遵循 72 列与 BREAKING CHANGE: 约定；
4. 提交前 git fetch origin && git rebase origin/main 保持与上游同步；
5. 按 .github/PULL_REQUEST_TEMPLATE.md 完整填写描述与 Checklist，附上对应用开发者可读的 Release Notes；
6. 推送到 fork，耐心处理评审意见并等待对应 Code Owner 批准；
7. 关注 CI 结果，若为平台性故障或 flaky 误报，请维护者重启 CI。

Electron 的合入门槛较高，但这套从"签名提交 + 语义化消息"到"Code Owner 审批 + 全平台 CI"的流程，本质上是一套大型开源项目在安全与质量之间的平衡实践。遵循上述 11 步流程提 PR，不仅能显著提高合入效率，也能让你的改动在 spec/、docs/api/ 等长期维护的资产中沉淀出可追溯的价值。