拉取请求

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

设置本地开发环境

步骤 1：Fork

在 GitHub 上 Fork 该项目，并在本地克隆您的 Fork。

$ git clone git@github.com: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: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on 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：Rebase

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

$ git fetch upstream
$ git rebase upstream/main

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

步骤 7：测试

错误修复和功能应始终附带测试。我们提供了一份测试指南，以使该过程更容易。查看其他测试以了解它们的结构方式也可能会有所帮助。

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

$ npm run test

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

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

$ 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：合并

为了合并，拉取请求需要至少一位 Electron 代码所有者审查和批准，并Pass CI。之后，如果没有其他贡献者反对，则可以合并拉取请求。

恭喜您，感谢您的贡献！

持续集成测试

每个拉取请求都在持续集成 (CI) 系统上进行测试，以确认它在 Electron 支持的平台上工作。

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

当您打开拉取请求时，CI 会自动启动，但只有核心维护人员可以重启 CI 运行。如果您认为 CI 给出了误报，请要求维护人员重启测试。