拉取请求

• 设置本地环境
  • 步骤 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

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

提交消息指南

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

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

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

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

常见前缀

• fix: 修复 bug
• feat: 添加新功能
• docs: 文档更改
• test: 添加缺失的测试或修正现有测试
• build: 影响构建系统的更改
• ci: 更改 CI 配置文件和脚本
• perf: 提高性能的代码更改
• refactor: 既不修复 bug 也不添加功能的代码更改
• 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 main 分支的最新更改。

步骤 7: 测试

bug 修复和新功能应该始终伴随测试。 提供了一份测试指南，以使过程更容易。 查看其他测试的结构也有帮助。

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

$ npm run test

确保 linter 没有报告任何问题，并且所有测试都通过。 请不要提交无法通过任何一项检查的补丁。

如果你正在更新测试并想运行单个 spec 进行检查

$ npm run test -match=menu

上述命令只会运行匹配 menu 的 spec 模块，这对于那些正在进行否则将在测试周期末尾进行的测试的人来说非常有用。

步骤 8: 推送

一旦你的提交准备就绪——通过测试和 linting——就可以通过将你的工作分支推送到你在 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 给出了假阴性结果，请要求维护人员重新启动测试。