拉取请求

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

设置你的本地环境

步骤 1：Fork

在 GitHub 上 Fork 该项目 https://github.com/electron/electron 并将你的 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/electron 仓库强制执行 提交签名 用于所有传入的 PR。要签名你的提交，请参阅 GitHub 关于 告知 Git 你的签名密钥 的文档。

提交消息指南

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

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

带有语义前缀的提交消息示例

• fix: 不要在未阻止默认行为时覆盖 prevent_default
• feat: 添加 app.isPackaged() 方法
• docs: app.isDefaultProtocolClient 现在在 Linux 上可用

常用前缀

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

编写提交消息时需要记住的其他事项

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 主分支的最新更改。

步骤 7：测试

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

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

$ npm run test

确保 linter 没有报告任何问题，并且所有测试都通过。请勿提交未能通过任一检查的补丁。

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

$ npm run test -match=menu

以上将仅运行与 menu 匹配的规范模块，这对于正在处理否则将在测试周期末尾的测试的人来说非常有用。

步骤 8：推送

一旦你的提交准备好，通过将你的工作分支推送到 GitHub 上的你的 Fork，开始打开拉取请求的过程，并且测试和 linting 都通过了。

$ 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 的所有平台上通过测试（“显示绿色”）。 这意味着所有测试都通过并且没有 linting 错误。 然而，CI 基础设施本身在特定平台上失败或所谓的“不稳定的”测试失败（“显示红色”）的情况并不少见。 每次 CI 失败都必须手动检查以确定原因。

CI 在您打开 pull request 时自动启动，但只有核心维护者可以重新启动 CI 运行。 如果您认为 CI 给出的是误报，请要求维护者重新启动测试。