拉取请求

• 设置本地开发环境
  • 步骤 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 main 的最新更改。

步骤 7: 测试

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

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

$ npm run test

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

如果要更新测试并运行单个规范以进行检查

$ npm run test -match=menu

上述命令只会运行与 menu 匹配的 spec 模块，这对于任何正在进行测试的人员来说都很有用，否则这些测试将在测试周期的最后执行。

步骤 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 代码所有者审阅并批准，并且通过 CI。之后，如果没有其他贡献者提出异议，则可以合并拉取请求。

恭喜您，感谢您的贡献！

持续集成测试

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

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

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