Electron 源码贡献指南:从 Issue 到 Pull Request 的完整工作流、测试与代码规范

Electron 仓库的根目录文件 CONTRIBUTING.md 定义了向 Electron 项目提交贡献的总纲:Issue 如何报告与跟踪、Pull Request(PR)需要经历哪些步骤、哪些文件只有维护者才能改动、以及使用 AI 工具协作的边界。本文以该文档为骨架,结合仓库内 docs/development/ 下的开发指南、根目录 package.json 中的 lint/test 脚本与 script/spec-runner.js 测试入口,把「提 Issue → 改代码 → 测试 → 提交 → 合并」的全链路拆解成可复制的操作步骤,帮助你在动手前就熟悉 Electron 贡献者的完整规则体系。

贡献的两种基本形式与前置约定

CONTRIBUTING.md 开篇明确了两个原则:项目遵循 Contributor Covenant 行为准则(见 CODE_OF_CONDUCT.md);贡献指南"只是指导方针而非硬性规则",并欢迎贡献者直接提 PR 修改这份文档本身。

对任何一个 Issue,存在三种贡献方式(与 docs/development/issues.md 一致):

1. 开 Issue 讨论:认为发现了新 Bug 时,在 issue tracker 创建新 Issue;
2. 协助分类(triage):提供可复现的测试用例,或提出解决思路;
3. 协助解决:证明该问题不是 Bug 或已被修复,更常见的是提交一个具体、可评审的 PR。

Electron 构建在 Chromium 与 Node.js 两大上游项目之上,绝大多数 PR 涉及的四类改动分别位于:shell/ 目录(C/C++ 原生代码)、lib/ 目录(TypeScript/JavaScript 胶水层)、docs/ 文档、spec/ 测试。这一目录划分在 docs/development/pull-requests.md 与 docs/development/source-code-directory-structure.md 中都有对应说明。

Issue 的语言政策与关闭策略

CONTRIBUTING.md 对 Issue 社区做了两条有实操意义的约定:

• 语言:接受任何语言的 Issue。非英文 Issue 欢迎任何人补充英文翻译回复(可借助翻译软件,保留原文+译文可减少翻译误差);回复是否用原语言不限。但明确警告:以非英文为手段规避行为准则会被立即、可能永久地禁止参与项目;
• 关闭策略:当 Issue 处于无活动状态、且其影响的最新版本已停止受支持时,会被关闭。Electron 同时维护最近三个主版本,每个主版本按 8 周节奏发布。被误关的 Issue 可以随时 @ 维护者或追加评论来重新激活。

Pull Request 全流程:11 个步骤逐条落地

docs/development/pull-requests.md 把 PR 流程拆成 11 步,下面逐步给出当前仓库中可验证的操作细节。

Step 1-2:Fork 与本地构建

官方推荐使用 @electron/build-tools 完成初始化,而不是手动同步依赖:

# 全局安装 build-tools
npm install -g @electron/build-tools
# 在你希望克隆项目的目录执行,--fork 指向你的 fork
e init --fork my-org/electron --bootstrap testing

执行后会在当前目录生成嵌套结构的 electron 目录,你的 fork 实际位于 electron/src/electron,其中 git 配置了两个 remote:origin 指向上游仓库,fork 指向你的 fork。依赖同步、增量编译等后续操作参见 docs/development/build-instructions-gn.md 及各平台构建文档(macOS、Windows、Linux)。

Step 3:从 main 切分支

git checkout -b my-branch

分支应直接从 main 切出,保持开发环境清晰。

Step 4:改代码,顺手跑 lint

改动 shell/、lib/、docs/、spec/ 之外,还要时刻注意风格检查。根目录 package.json 定义了汇总入口:

yarn lint

它实际串起了 script/lint.js(按改动区域分发检查)、lint:fmt(oxfmt 格式化检查)、lint:docs(文档链路:markdown 内 JS 检查、TypeScript 定义生成、相对链接检查、markdownlint、API 历史检查)以及 lint:chromium-roller(Chromium 变更滚动检查)。更细粒度的命令包括 lint:clang-format(C/C++ 格式化)、lint:clang-tidy、lint:cpp、lint:py、lint:gn(构建文件)等,全部列在 package.json 的 scripts 字段中。docs/development/testing.md 还提到:很多 lint 检查已包含在 precommit hook 里,提交时大概率会先于 CI 拦住问题——这与 package.json 中 lint-staged 配置一一对应,例如 *.md 触发 npm run lint:docs、*.{gn,gni} 触发 gn-check、{*.patch,.patches} 触发 patch 检查、DEPS 触发文件名/revision 生成脚本等。

Step 5:提交——语义化 Commit 与签名

Electron 采用[语义化提交信息](https://conventionalcommits.org/ 的规范,PR 标题必须带语义前缀,否则无法合并。常见前缀:

前缀	含义
fix	缺陷修复
feat	新功能
docs	文档变更
test	补充或修正测试
build	影响构建系统的变更
ci	CI 配置与脚本变更
perf	性能改进
refactor	既不修 Bug 也不加功能的代码重构
style	不影响语义的变更(如 lint)

消息写作规则(来自 docs/development/pull-requests.md):

1. 首行短描述,建议 50 字符以内、最多 72 字符,全小写(专有名词、缩写与代码名除外);
2. 第二行留空;
3. 其余行按 72 列换行;
4. 破坏性 API 变更在正文或 footer 中以 BREAKING CHANGE: 开头标注,任何类型(fix/feat/chore 等)的提交都可以携带;
5. 建议将改动按逻辑拆成多个小提交,便于评审;合入时多个 commit 会被 squash,因此提交数量不限。

此外仓库强制提交签名:所有入站 PR 的 commit 必须带签名,配置方式参照 GitHub 关于签署 commit 的文档(在 PR 描述里说明即可,无需在此展开外部链接)。

Step 6:用 rebase 同步主线

git fetch origin
git rebase origin/main

同步主线时用 git rebase 而不是 git merge,保证分支基于最新 main。

Step 7:跑完整测试套件

Bug 修复与新功能必须附带测试,且提交前要跑完整套件:

yarn test            # 或 npm run test,等价于 node script/spec-runner.js

只跑匹配某模式的单个 spec 模块:

yarn test -match=menu        # 只运行文件名匹配 menu 的 spec
npm run test -- -g ipc       # testing.md 给出的写法,-g 为正则 grep

从 script/spec-runner.js 可以看到其实现:未知命令行参数会被收集后透传给以 Electron 自身运行的 mocha 测试进程,这正是 -match / -g 能生效的原因;而 docs/development/testing.md 同时提醒,若未使用 build-tools,本地构建名须为 Testing、Release、Default 之一或设置 ELECTRON_OUT_DIR,否则测试前置步骤会失败。

Step 8-9:推送到 fork 并填写 PR 模板

git push fork my-branch

在 GitHub 上创建 PR 时会展示模板 .github/PULL_REQUEST_TEMPLATE.md。该文档明确指出:模板填写不充分会因维护者追问细节而延迟合并。

Step 10:讨论与"批准/要求修改"工作流

PR 需要所改区域的 Code Owner 批准才能合入,权限映射定义在 .github/CODEOWNERS。维护者可能请求改动,范围从改错字到实质重构不等;评审意见有时会显得突兀,文档给出的建议是:若认为评审不公,说出来或寻求其他贡献者意见,多数情况下是评审时间不足而非恶意,耐心沟通即可化解。修改现有 PR 的方式:本地改完追加 commit 再 git push fork my-branch,GitHub 会自动更新 PR。

Step 11:合入(landing)与 CI

合入条件:至少一名 Electron Code Owner 评审通过 + CI 全绿 + 无其他贡献者异议。每个 PR 都会在 CI 上于受支持平台跑全量测试;偶发的 CI 基础设施故障或 flaky 测试(红灯)需要人工甄别,且只有核心维护者能重启 CI 运行——若你认为是误报,请在 PR 里请维护者重启。

依赖升级政策:package.json 与 yarn.lock 只归维护者

CONTRIBUTING.md 中有独立一节"Dependencies Upgrades Policy":Electron 根目录 package.json 或 yarn.lock 的改动只允许维护者进行,出于安全考虑不接受直接修改这两个文件的 PR;贡献者应在 issue tracker 里提出升级请求。若改动复杂,欢迎以 draft PR 形式给出方案,但会被关闭并由维护者提交重复 PR 替代。当前仓库使用 Yarn 4("packageManager": "yarn@4.12.0",见 package.json),并以 resolutions 字段锁定部分传递依赖(如 minimist、js-yaml 的指定版本),这也是升级请求需要谨慎对待的背景。

AI 工具政策:必须有人类在环

CONTRIBUTING.md 专门设立了 AI Tool Policy 一节:凡以任何方式使用 AI 工具为项目做贡献,须遵守 Electron 治理仓库中的 AI 政策;未审核的 AI 生成贡献会浪费维护者时间,将被拒绝。核心结论一句话:there must be a human in the loop——你负责审核、理解并能解释自己的贡献,AI 辅助不改变这一点。文件内嵌注释同样要求 coding agent 必须遵守该政策。对使用编码代理的读者,这是仓库层面的硬性约束,写代码前应先确认自己具备完整审阅与解释改动的能力。

代码风格速览:各语言各自遵循什么

CONTRIBUTING.md 的 Style Guides 一节指向 docs/development/coding-style.md,其要点值得在改代码前过一遍:

• 通用:文件以换行符结尾;require 按"Node 内建模块 → Electron 内建模块 → 相对路径本地模块"排序;类静态成员先于实例成员;避免平台相关代码(用 path.join() 拼路径,用 os.tmpdir() 而非 /tmp);函数末尾显式返回用裸 return;
• C++/Python:遵循 Chromium 编码风格,Python 使用 3.9;script/cpplint.py 与 script/run-clang-tidy.ts 做自动检查;C++ 大量使用 Chromium 抽象类型(作用域类型、日志机制等),建议先熟悉 Chromium 的数据结构文档;
• JavaScript:standard 风格;.js 文件名用 - 连接(如 file-name.js);优先 ES6+ 语法(const/let、箭头函数、模板字符串);
• 命名:API 命名对齐 Node.js 惯例——类用 PascalCase(BrowserWindow),API 集合用 camelCase(globalShortcut),复杂子对象用混合命名(win.webContents);新 API 优先 getter/setter 风格(getText()/setText(text) 优于 .text([text]));
• 文档:写作遵循 docs/development/style-guide.md,用 npm run lint:docs 校验格式。

进阶方向:Patches、新 API 与治理

CONTRIBUTING.md 的 Further Reading 指向 docs/development/,其中与贡献直接相关的进阶主题包括:

• Patches 管理:Electron 对 Chromium、Node.js 等上游维护着成组补丁,集中在 patches/ 目录(可按项目分组的 .patch 文件,如 patches/node/、patches/v8/),新增或修改补丁的流程见 docs/development/patches.md;
• 新增 API 模块:完整流程见 docs/development/creating-api.md;
• Chromium / V8 联动开发:分别见 docs/development/chromium-development.md 与 docs/development/v8-development.md;
• 治理体系:Electron 设有完整治理机制,API、发布、依赖升级(Chromium/Node.js)各有工作组负责,频繁贡献者可考虑加入相应工作组;
• 调试 Electron 自身(而非用 Electron 写的 App):见 docs/development/debugging.md 及各平台调试文档。

贡献前自检清单

综合 CONTRIBUTING.md 与仓库内脚本、配置,提交 PR 前可对照检查:

1. 改动落在 shell/、lib/、docs/、spec/ 等允许区域,未触碰 package.json/yarn.lock(依赖升级走 issue 请求);
2. yarn lint 通过(对应 package.json 的汇总 lint 链);
3. Bug 修复/新功能附带测试,yarn test 全量通过,必要时用 -match= 或 -g 定向回归;
4. commit 信息带语义前缀、符合 72 列格式,且所有 commit 已签名;
5. 分支已 rebase 到最新 origin/main;
6. PR 模板 .github/PULL_REQUEST_TEMPLATE.md 填写完整;
7. 若使用了 AI 工具,已逐行审阅并能解释每一处改动;
8. 等待对应 Code Owner(.github/CODEOWNERS)批准与 CI 绿灯。

遵守以上流程,你的贡献就具备了在 Electron 项目评审体系中顺利合入的全部要素。