请求请求

🌐 Pull Requests

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

设置你的本地环境

🌐 Setting up your local environment

步骤 1：分叉

🌐 Step 1: Fork

在 GitHub 上分叉该项目，并将你的分叉本地克隆。

🌐 Fork the project on GitHub and clone your fork locally.

$ git clone git@github.com:username/electron.git
$ cd electron
$ git remote add upstream https://github.com/electron/electron.git
$ git fetch upstream

步骤2：构建

🌐 Step 2: Build

构建步骤和依赖会根据你的操作系统略有不同。 请参阅这些关于本地构建 Electron 的详细指南：

🌐 Build steps and dependencies differ slightly depending on your operating system. See these detailed guides on building Electron locally:

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

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

🌐 Once you've built the project locally, you're ready to start making changes!

步骤 3：分支

🌐 Step 3: Branch

为了保持开发环境的整洁，请创建本地分支来存放你的工作。这些分支应直接从 main 分支上分出。

🌐 To keep your development environment organized, create local branches to hold your work. These should be branched directly off of the main branch.

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

做出改变

🌐 Making Changes

步骤 4：编码

🌐 Step 4: Code

大多数针对 electron/electron 仓库提交的 pull 请求都包含对以下内容的修改：shell/ 文件夹中的 C/C++ 代码、lib/ 文件夹中的 JavaScript 代码、docs/api/ 中的文档或 spec/ 文件夹中的测试。

🌐 Most pull requests opened against the electron/electron repository include changes to either the C/C++ code in the shell/ folder, the JavaScript code in the lib/ folder, the documentation in docs/api/ or tests in the spec/ folder.

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

🌐 Please be sure to run npm run lint from time to time on any code changes to ensure that they follow the project's code style.

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

🌐 See coding style for more information about best practice when modifying code in different parts of the project.

步骤5：提交

🌐 Step 5: Commit

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

🌐 It is recommended to keep your changes grouped logically within individual commits. Many contributors find it easier to review changes that are split across multiple commits. There is no limit to the number of commits in a pull request.

$ git add my/changed/files
$ git commit

请注意，多个提交在落地时会被压缩。

🌐 Note that multiple commits get squashed when they are landed.

提交签名

🌐 Commit signing

electron/electron 仓库对所有提交的 PR 强制要求 提交签名。 要为你的提交签名，请参阅 GitHub 关于 告诉 Git 你的签名密钥 的文档。

🌐 The electron/electron repo enforces commit signatures for all incoming PRs. To sign your commits, see GitHub's documentation on Telling Git about your signing key.

提交消息指南

🌐 Commit message guidelines

一个好的提交信息应该描述发生了什么变化以及为什么发生变化。Electron 项目使用语义化提交信息来简化发布进程。

🌐 A good commit message should describe what changed and why. The Electron project uses semantic commit messages to streamline the release process.

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

🌐 Before a pull request can be merged, it must have a pull request title with a semantic prefix.

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

🌐 Examples of commit messages with semantic prefixes:

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient is now available on Linux

常见前缀：

🌐 Common prefixes:

• 修复：一个漏洞修复
• 特性：新增功能
• 文档：文档更改
• 测试：添加缺失的测试或修复现有的测试
• 构建：影响构建系统的更改
• ci：对我们的 CI 配置文件和脚本的更改
• perf：提高性能的代码更改
• 重构：一种既不修复错误也不添加新功能的代码更改
• 风格：不会影响代码含义的更改（代码规范检查）

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

🌐 Other things to keep in mind when writing a commit message:

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

重大变化

🌐 Breaking Changes

一个提交如果在其可选的正文或页脚部分开头包含文本 BREAKING CHANGE:，则表示引入了破坏性 API 更改（与语义版本控制中的 Major 对应）。破坏性更改可以包含在任何类型的提交中。例如，fix:、feat: 和 chore: 类型都是有效的，除此之外，任何其他类型也同样有效。

🌐 A commit that has the text BREAKING CHANGE: at the beginning of its optional body or footer section introduces a breaking API change (correlating with Major in semantic versioning). A breaking change can be part of commits of any type. e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.

详情请参见 conventionalcommits.org。

🌐 See conventionalcommits.org for more details.

第6步：变基

🌐 Step 6: Rebase

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

🌐 Once you have committed your changes, it is a good idea to use git rebase (not git merge) to synchronize your work with the main repository.

$ git fetch upstream
$ git rebase upstream/main

这确保你的工作分支包含来自 electron/electron main 的最新更改。

🌐 This ensures that your working branch has the latest changes from electron/electron main.

第七步：测试

🌐 Step 7: Test

错误修复和新功能应该始终配有测试。我们提供了一份测试指南来简化这一进程。查看其他测试以了解它们应该如何构建也会有帮助。

🌐 Bug fixes and features should always come with tests. A testing guide has been provided to make the process easier. Looking at other tests to see how they should be structured can also help.

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

🌐 Before submitting your changes in a pull request, always run the full test suite. To run the tests:

$ npm run test

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

🌐 Make sure the linter does not report any issues and that all tests pass. Please do not submit patches that fail either check.

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

🌐 If you are updating tests and want to run a single spec to check it:

$ npm run test -match=menu

上述内容只会运行匹配 menu 的规范模块，这对于正在处理原本会在测试周期末尾执行的测试的人来说非常有用。

🌐 The above would only run spec modules matching menu, which is useful for anyone who's working on tests that would otherwise be at the very end of the testing cycle.

第8步：推动

🌐 Step 8: Push

一旦你的提交准备就绪——测试通过且代码风格检查无误——就可以通过将你的工作分支推送到 GitHub 上的 fork 来开始创建拉取请求的进程。

🌐 Once your commits are ready to go -- with passing tests and linting -- begin the process of opening a pull request by pushing your working branch to your fork on GitHub.

$ git push origin my-branch

步骤 9：创建拉取请求

🌐 Step 9: Opening the Pull Request

在 GitHub 内，打开一个新的拉取请求时会显示一个模板，需要填写。可以在这里找到。

🌐 From within GitHub, opening a new pull request will present you with a template that should be filled out. It can be found here.

如果你未能充分填写此模板，你的拉取请求可能会被延迟合并，因为维护者需要更多信息或澄清不明确之处。

🌐 If you do not adequately complete this template, your PR may be delayed in being merged as maintainers seek more information or clarify ambiguities.

步骤10：讨论并更新

🌐 Step 10: Discuss and update

你可能会收到关于你的拉取请求的反馈或修改请求。这是提交进程中的一个重要部分，所以不要灰心！有些贡献者可能会立即批准拉取请求，而其他人可能会有详细的评论或反馈。这是评估更改是否正确和必要的必要步骤。

🌐 You will probably get feedback or requests for changes to your pull request. This is a big part of the submission process so don't be discouraged! Some contributors may sign off on the pull request right away. Others may have detailed comments or feedback. This is a necessary part of the process in order to evaluate whether the changes are correct and necessary.

要对现有的拉取请求进行更改，请在本地分支上进行更改，添加一个包含这些更改的新提交，然后将其推送到你的分支。GitHub 会自动更新拉取请求。

🌐 To make changes to an existing pull request, make the changes to your local branch, add a new commit with those changes, and push those to your fork. GitHub will automatically update the pull request.

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

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

🌐 There are a number of more advanced mechanisms for managing commits using git rebase that can be used, but are beyond the scope of this guide.

如果你在等待某个问题的答复，可以随时在拉取请求中发表评论以提醒审核者。如果遇到看起来不熟悉的单词或缩略词，请参考此词汇表。

🌐 Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer on something. If you encounter words or acronyms that seem unfamiliar, refer to this glossary.

批准和请求变更工作流

🌐 Approval and Request Changes Workflow

所有拉取请求都需要经过你所修改区域的代码负责人批准才能合并。每当维护者审查拉取请求时，他们可能会要求进行修改。这些修改可能很小，比如修复一个拼写错误，也可能涉及实质性的更改。此类请求的目的是提供帮助，但有时可能显得生硬或不够有用，尤其是当它们没有包含具体的修改建议时。

🌐 All pull requests require approval from a Code Owner of the area you modified in order to land. Whenever a maintainer reviews a pull request they may request changes. These may be small, such as fixing a typo, or may involve substantive changes. Such requests are intended to be helpful, but at times may come across as abrupt or unhelpful, especially if they do not include concrete suggestions on how to change them.

尽量不要灰心。如果你觉得某条审查不公平，可以直接提出，或者寻求其他项目贡献者的意见。通常这样的评论是因为审查者没有花足够的时间进行审查，而不是出于恶意。这类问题通常可以通过一些耐心来解决。话虽如此，我们仍应期望审查者提供有帮助的反馈。

🌐 Try not to be discouraged. If you feel that a review is unfair, say so or seek the input of another project contributor. Often such comments are the result of a reviewer having taken insufficient time to review and are not ill-intended. Such difficulties can often be resolved with a bit of patience. That said, reviewers should be expected to provide helpful feedback.

第11步：着陆

🌐 Step 11: Landing

为了合并，一个拉取请求需要至少由一位 Electron 代码负责人审查并批准，并通过持续集成（CI）。之后，如果其他贡献者没有异议，该拉取请求就可以被合并。

🌐 In order to land, a pull request needs to be reviewed and approved by at least one Electron Code Owner and pass CI. After that, if there are no objections from other contributors, the pull request can be merged.

祝贺并感谢你的贡献！

🌐 Congratulations and thanks for your contribution!

持续集成测试

🌐 Continuous Integration Testing

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

🌐 Every pull request is tested on the Continuous Integration (CI) system to confirm that it works on Electron's supported platforms.

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

🌐 Ideally, the pull request will pass ("be green") on all of CI's platforms. This means that all tests pass and there are no linting errors. However, it is not uncommon for the CI infrastructure itself to fail on specific platforms or for so-called "flaky" tests to fail ("be red"). Each CI failure must be manually inspected to determine the cause.

当你打开拉取请求时，CI 会自动启动，但只有核心维护者可以重新启动 CI 运行。如果你认为 CI 给出了错误的否定结果，请要求维护者重新运行测试。

🌐 CI starts automatically when you open a pull request, but only core maintainers can restart a CI run. If you believe CI is giving a false negative, ask a maintainer to restart the tests.