拉取请求

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

设置本地环境

步骤 1：Fork

在 GitHub 上 fork 项目并克隆你的 fork 到本地。

$ git clone [email protected]:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream

步骤 2：构建

构建步骤和依赖项因操作系统而略有不同。请参阅这些有关在本地构建 Electron 的详细指南

• 在 macOS 上构建
• 在 Linux 上构建
• 在 Windows 上构建

在本地构建项目后，就可以开始进行更改了！

步骤 3：分支

为了保持开发环境的井然有序，请创建本地分支来保存你的工作。这些分支应该直接从 main 分支分支出来。

$ git checkout -b my-branch -t upstream/main

进行更改

步骤 4：编码

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

请确保不时运行 npm run lint 以检查任何代码更改，以确保它们遵循项目的代码风格。

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

步骤 5：提交

建议将你的更改在逻辑上分组到各个提交中。许多贡献者发现更容易查看跨多个提交拆分的更改。拉取请求中的提交数量没有限制。

$ git add my/changed/files
$ git commit

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

提交信息指南

良好的提交信息应该描述更改的内容以及原因。Electron 项目使用 语义化提交信息 来简化发布流程。

在拉取请求能够合并之前，**必须**在拉取请求标题中包含语义前缀。

包含语义前缀的提交信息的示例

• fix: 如果默认值未阻止，则不要覆盖 prevent_default
• feat: 添加 app.isPackaged() 方法
• docs: app.isDefaultProtocolClient 现在在 Linux 上可用

常见前缀

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

编写提交信息时需要牢记的其他事项

1. 第一行应
   • 包含对更改的简短描述（最好不超过 50 个字符，最多不超过 72 个字符）
   • 完全小写，除了专有名词、首字母缩略词以及指代代码的单词（如函数/变量名）
2. 将第二行留空。
3. 将所有其他行在第 72 列处换行。

重大更改

在可选的正文或脚注部分开头包含文本 BREAKING CHANGE: 的提交引入了重大 API 更改（与语义版本控制中的 Major 相对应）。重大更改可以是任何类型的提交的一部分。例如，fix:、feat: 和 chore: 类型都是有效的，除了任何其他类型。

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

步骤 6：变基

提交更改后，最好使用 git rebase（而不是 git merge）将你的工作与主存储库同步。

$ git fetch upstream
$ git rebase upstream/main

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

步骤 7：测试

错误修复和功能应始终附带测试。已提供 测试指南 以简化此过程。查看其他测试以了解其结构也可以有所帮助。

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

$ npm run test

确保 linter 未报告任何问题并且所有测试都已通过。请不要提交导致任一检查失败的补丁。

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

$ npm run test -match=menu

以上只会运行与 menu 匹配的规范模块，这对任何正在处理测试的人都有用，否则这些测试将在测试周期的最后阶段。

步骤 8：推送

一旦你的提交准备就绪——通过了测试和代码风格检查——通过将你的工作分支推送到 GitHub 上的 fork 来开始打开拉取请求的过程。

$ git push origin my-branch

步骤 9：打开拉取请求

在 GitHub 中，打开新的拉取请求将向你显示一个需要填写的模板。它可以在 此处 找到。

如果你没有充分完成此模板，你的 PR 可能会延迟合并，因为维护者需要更多信息或澄清歧义。

步骤 10：讨论和更新

你可能会收到有关拉取请求的反馈或更改请求。这是提交过程的重要组成部分，所以不要气馁！一些贡献者可能会立即签署拉取请求。其他人可能会有详细的评论或反馈。这是评估更改是否正确和必要的过程的必要部分。

要对现有的拉取请求进行更改，请对你的本地分支进行更改，使用这些更改添加新的提交，并将它们推送到你的 fork。GitHub 会自动更新拉取请求。

$ git add my/changed/files
$ git commit
$ git push origin my-branch

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

如果你正在等待某个问题的答案，请随时在拉取请求中发布评论以 ping 审阅者。如果你遇到不熟悉的单词或首字母缩略词，请参考此 词汇表。

批准和请求更改工作流程

所有拉取请求都需要你修改的区域的 代码所有者 批准才能合并。每当维护者审阅拉取请求时，他们可能会请求更改。这些更改可能很小，例如更正错别字，或者可能涉及实质性更改。此类请求旨在提供帮助，但有时可能会显得唐突或无益，尤其是在它们不包含有关如何更改它们的具体建议时。

尽量不要气馁。如果你认为审阅不公平，请说明情况或征求其他项目贡献者的意见。通常，此类评论是审阅者花费的时间不足以进行审阅的结果，并非恶意。此类困难通常可以通过一些耐心来解决。也就是说，应该期望审阅者提供有益的反馈。

步骤 11：合并

为了合并代码，一个 Pull Request 需要至少一位 Electron 代码所有者审查并批准，并且通过 CI 测试。之后，如果没有其他贡献者反对，Pull Request 就可以合并。

恭喜你并感谢你的贡献！

持续集成测试

每个 Pull Request 都会在持续集成 (CI) 系统上进行测试，以确认它在 Electron 支持的平台上都能正常工作。

理想情况下，Pull Request 会在所有 CI 平台上通过（显示为“绿色”）。这意味着所有测试都通过且没有代码风格错误。但是，CI 基础设施本身在特定平台上出现故障或所谓的“不稳定”测试失败（显示为“红色”）的情况并不少见。每个 CI 失败都需要手动检查以确定原因。

当您打开一个 Pull Request 时，CI 会自动开始，但只有核心维护者才能重新启动 CI 运行。如果您认为 CI 给出了错误的否定结果，请让维护者重新启动测试。