Skip to main content

请求请求

¥Pull Requests

设置你的本地环境​

¥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:

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

¥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 存储库打开的大多数拉取请求都包括对 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 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:

  • 使固定：错误修复

    ¥fix: A bug fix

  • 壮举：一个新功能

    ¥feat: A new feature

  • 文档：文档变更

    ¥docs: Documentation changes

  • 测试：添加缺失的测试或纠正现有测试

    ¥test: Adding missing tests or correcting existing tests

  • 构建：影响构建系统的更改

    ¥build: Changes that affect the build system

  • 词：CI 配置文件和脚本的更改

    ¥ci: Changes to our CI configuration files and scripts

  • 性能：提高性能的代码更改

    ¥perf: A code change that improves performance

  • 重构：既不修复错误也不添加功能的代码更改

    ¥refactor: A code change that neither fixes a bug nor adds a feature

  • 风格：不影响代码含义的更改（linting）

    ¥style: Changes that do not affect the meaning of the code (linting)

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

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

  1. 第一行应该：

    ¥The first line should:

    • 包含变更的简短描述（最好不超过 50 个字符，且不超过 72 个字符）

      ¥contain a short description of the change (preferably 50 characters or less, and no more than 72 characters)

    • 除了专有名词、首字母缩略词和引用代码的单词（例如函数/变量名称）外，全部使用小写

      ¥be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names

  2. 将第二行保留为空。

    ¥Keep the second line blank.

  3. 将所有其他行换行至 72 列。

    ¥Wrap all other lines at 72 columns.

重大变化​

¥Breaking Changes

在其可选正文或页脚部分开头具有文本 BREAKING CHANGE: 的提交引入了重大 API 更改（与语义版本控制中的主要相关）。重大更改可以是任何类型提交的一部分。例如，除了任何其他类型之外，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 主分支的最新更改。

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

步骤 7：测试​

¥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

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

¥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

一旦你的提交准备就绪（通过测试和 linting），就可以通过将你的工作分支推送到 GitHub 上的分支来开始打开拉取请求的过程。

¥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.

如果你没有充分完成此模板，你的 PR 可能会被延迟合并，因为维护人员会寻求更多信息或澄清歧义。

¥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.

如果你正在等待某件事的答案，请随时在拉取请求中发表评论以向审阅者发送评论。如果你遇到不熟悉的单词或首字母缩略词，请参阅此 glossary。

¥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 平台上通过 ("是绿色的")。这意味着所有测试都通过并且没有 linting 错误。然而，CI 基础设施本身在特定平台上失败或所谓的 "flaky" 测试失败 ("变红") 的情况并不少见。每个 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.