拉取请求¶

• 设置本地环境
• 步骤 1：Fork
• 步骤 2：构建
• 步骤 3：分支
• 进行更改
• 步骤 4：编码
• 步骤 5：提交
  • 提交信息指南
• 步骤 6：变基
• 步骤 7：测试
• 步骤 8：推送
• 步骤 9：打开拉取请求
• 步骤 10：讨论和更新
  • 批准和请求更改工作流
• 步骤 11：落地
• 持续集成测试

设置本地环境¶

步骤 1：Fork¶

Fork Electron 的 GitHub 仓库。

步骤 2：构建¶

我们建议使用 @electron/build-tools 来构建 Electron 本身。

# Install build-tools package globally:
npm install -g @electron/build-tools
# Run the init script where you want to clone the project and point it to your fork:
e init --fork my-org/electron --bootstrap testing

这将在你的工作目录中创建一个新的 electron 文件夹并初始化项目。 构建完成后，导航到 electron/src/electron，你的 fork 实际克隆在那里。

[!IMPORTANT] 你的 Electron 项目具有复杂的文件夹结构和嵌套仓库。 请参阅 构建说明 文档，了解详细的 Build Tools 使用说明（例如如何同步依赖项或如何重新编译二进制文件） 以及平台特定注意事项。

在那里，你的 git 中应该有两个 remote URL：

• origin 指向 electron/electron
• fork 指向你的 fork（my-org/electron）

一旦你在本地构建完项目，就可以开始进行更改了！

步骤 3：分支¶

为了保持开发环境整洁，创建本地分支来 存放你的工作。这些分支应直接从 main 分支创建。

git checkout -b my-branch

进行更改¶

步骤 4：编码¶

针对 electron/electron 仓库打开的大多数拉取请求都包含 对 shell/ 文件夹中的 C/C++ 代码、 lib/ 文件夹中的 JavaScript 代码、docs/api/ 中的文档 或 spec/ 文件夹中的测试的更改。

请务必不时地对任何代码更改运行 yarn lint， 以确保它们符合项目的代码风格。

有关在项目不同部分修改代码时的最佳实践，请参阅 编码风格。

步骤 5：提交¶

建议将更改在单独的提交中按逻辑分组。许多贡献者发现，拆分到多个提交中的更改更容易审查。拉取请求中的提交数量没有限制。

git add my/changed/files
git commit

注意，多个提交在合并落地时会被压缩。

提交签名¶

electron/electron 仓库对所有传入的 PR 强制要求 提交签名。 要签署你的提交，请参阅 GitHub 关于 告知 Git 你的签名密钥 的文档。

提交信息指南¶

一个好的提交信息应描述更改了什么以及为什么。Electron 项目 使用 语义化提交信息 来简化 发布流程。

在拉取请求可以合并之前，它必须具有带语义前缀的拉取请求标题。

带语义前缀的提交信息示例：

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

常见前缀：

• fix: 修复 bug
• feat: 新功能
• docs: 文档更改
• test: 添加缺失的测试或更正现有测试
• build: 影响构建系统的更改
• ci: 对 CI 配置文件和脚本的更改
• perf: 提高性能的代码更改
• refactor: 既不修复 bug 也不添加功能的代码更改
• style: 不影响代码含义的更改（linting）

编写提交信息时需要注意的其他事项：

1. 第一行应：
2. 包含更改的简短描述（最好不超过 50 个字符， 且不超过 72 个字符）
3. 除专有名词、缩写以及指代代码的词语（如函数/变量名）外，全部使用小写
4. 保持第二行为空。
5. 其他所有行在 72 列处换行。

破坏性变更¶

在其可选正文或页脚部分开头包含文本 BREAKING CHANGE: 的提交会引入破坏性 API 变更（对应语义化版本控制中的 Major）。破坏性变更可以是任何类型提交的一部分。 例如，fix:、feat: 和 chore: 类型都是有效的，此外任何其他类型也有效。

有关更多详细信息，请参阅 conventionalcommits.org。

步骤 6：变基¶

一旦你提交了更改，使用 git rebase （而不是 git merge）将你的工作与主仓库同步是个好主意。

git fetch origin
git rebase origin/main

这确保你的工作分支拥有来自 electron/electron main 的最新更改。

步骤 7：测试¶

bug 修复和功能应始终附带测试。已提供 测试指南 以简化流程。查看其他测试以了解它们应如何组织也会有所帮助。

在通过拉取请求提交更改之前，始终运行完整测试套件。要运行测试：

yarn test

请确保代码检查器不报告任何问题，并且所有测试都通过。 请不要提交未通过任一检查的补丁。

如果你正在更新测试，并希望运行单个 spec 来检查它：

yarn test -match=menu

上述命令只会运行匹配 menu 的 spec 模块，这对于那些正在处理原本会位于测试周期末尾的测试的人非常有用。

步骤 8：推送¶

当你的提交已准备就绪——测试和代码检查均通过——时，请通过向 GitHub 上的 fork 推送工作分支，开始创建拉取请求的流程。

git push fork my-branch

步骤 9：创建拉取请求¶

在 GitHub 中，创建新的拉取请求时会显示一个需要填写的模板。 可以在这里找到它。

如果你没有充分填写此模板，维护者可能需要更多信息或澄清模糊之处， 你的 PR 可能会被延迟合并。

步骤 10：讨论与更新¶

你很可能会收到针对拉取请求的反馈或修改要求。 这是提交流程的重要组成部分，所以不要气馁！一些 贡献者可能会立即批准拉取请求，另一些人可能会留下 详细的评论或反馈。这是流程中必要的部分， 用于评估这些更改是否正确且必要。

要对现有拉取请求进行修改，请在本地分支上做出更改， 添加包含这些更改的新提交，并将其推送到你的 fork。 GitHub 会自动更新拉取请求。

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

使用 git rebase 管理提交还有多种更高级的机制， 但它们超出了本指南的范围。

如果你在等待某件事的答复，可以在拉取请求中发表评论来提醒审阅者。 如果你遇到一些不熟悉的名词或缩写，请参考 Chromium 术语表。

批准与请求更改流程¶

所有拉取请求都需要你修改区域的 代码所有者 批准才能合并。每当维护者审阅拉取请求时， 他们可能会请求更改。这些更改可能很小，例如修复拼写错误， 也可能涉及实质性更改。这些请求本意是有帮助的， 但有时可能显得唐突或无益，尤其是当它们没有包含 关于_如何_更改的具体建议时。

尽量不要气馁。如果你觉得某次审阅不公平，可以直说， 或寻求其他项目贡献者的意见。通常，这类评论是审阅者 没有花足够时间审阅的结果，并非出于恶意。 这类困难通常可以通过一点耐心来解决。话虽如此， 审阅者应当被期望提供有帮助的反馈。

步骤 11：合并¶

为了合并，拉取请求需要至少一位 Electron 代码所有者 审阅并批准，并通过 CI。之后，如果其他贡献者 没有异议，就可以合并该拉取请求。

恭喜，感谢你的贡献！

持续集成测试¶

每个拉取请求都会在持续集成（CI）系统上进行测试， 以确认它在 Electron 支持的平台上的运行情况。

理想情况下，拉取请求会在 CI 的所有平台上通过（“变绿”）。 这意味着所有测试都通过，并且没有代码检查错误。然而， CI 基础设施本身在特定平台上失败，或所谓的“不稳定” 测试失败（“变红”）并不少见。每个 CI 失败都必须手动检查以确定原因。

当你创建拉取请求时，CI 会自动启动，但只有 核心维护者才能重新启动 CI 运行。如果你认为 CI 给出了 假阴性，请维护者重新启动测试。