• 设置您的本地环境

  • 步骤1: 复制
  • 步骤2: 构建
  • 步骤3: 分支

• 进行更改

  • 步骤4: 编写代码

  • 步骤5: 提交更改

    • 提交代码说明的指导
  • 步骤6: 合并分支
  • 步骤7: 测试
  • 步骤8: 推送代码
  • 步骤9: 新建一个合并代码请求

  • 步骤10: 讨论和更新

    • 批准和请求更改工作流程
  • 步骤11: 执行合并
  • 持续集成测试

Pull Requests

• Setting up your local environment

  • Step 1: Fork
  • Step 2: Build
  • Step 3: Branch

• Making Changes

  • Step 4: Code

  • Step 5: Commit

    • Commit message guidelines
  • Step 6: Rebase
  • Step 7: Test
  • Step 8: Push
  • Step 9: Opening the Pull Request

  • Step 10: Discuss and Update

    • Approval and Request Changes Workflow
  • Step 11: Landing
  • Continuous Integration Testing

设置您的本地环境

Setting up your local environment

步骤1: 复制

在 GitHub 上复制项目到你的账号并把项目克隆到本地。

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

Step 1: Fork

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: 构建

根据您的操作系统, 项目构建步骤和依赖项稍有不同。 请参阅这些关于构建 Electron 项目的详细指南:

• 在 MacOS 上构建
• 在 Linux 上构建
• 在 Windows 上构建

一旦您在本地构建了项目, 就可以开始进行更改了!

Step 2: Build

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

• Building on MacOS
• Building on Linux
• Building on Windows

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

步骤3: 分支

为了保持您的开发环境的组织, 创建本地分支来保存您的工作。 应该直接从 master 分支上创建您的分支。

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

Step 3: Branch

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

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

进行更改

Making Changes

步骤4: 编写代码

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

请确保都运行 npm run lint 在任何代码更改后, 以确保它们遵循项目的代码样式。

在项目的不同部分修改代码时, 有关最佳实践的更多信息, 请参见 编码样式 。

Step 4: Code

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

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: 提交更改

建议将更改按逻辑分组在每个独立提交中。 其他贡献者可以从拆分多个提交中更容易的检查代码的改变。 合并请求没有限制提交的数量。

$ git add my/changed/files
$ git commit

请注意, 在最后执行合并代码时多个提交通常会被合并。

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 often get squashed when they are landed.

提交代码说明的指导

好的提交说明应描述更改的内容和原因。 Electron项目使用语义化提交信息以精简发布过程。

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

带有语义化前缀的提交信息的样例：

• fix: don't overwrite prevent_default if default wasn't prevented
• feat: add app.isPackaged() method
• docs: app.isDefaultProtocolClient 现在在Linux可用

常见前缀：

- 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: 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
- style: Changes that do not affect the meaning of the code (linting)
- vendor: Bumping a dependency like libchromiumcontent or node

其他在写提交信息时需要留意的事情：

1. 第一行应该:

• 包含一个对代码改变的简短说明（最好少于或等于50个字符，最多不超过72个字符）
• 完全使用小写, 除了适当的名词, 缩写, 和引用代码的单词, 如函数/变量名

2. 将第二行留空。
3. 每行文字在72列处换行。

Commit message guidelines

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: 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
• style: Changes that do not affect the meaning of the code (linting)
• vendor: Bumping a dependency like libchromiumcontent or node

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

1. The first line should:

   • 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. Wrap all other lines at 72 columns.

重大更改

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). 一个重大更改可以是任何类型提交的一部分。 e.g., a fix:, feat: & chore: types would all be valid, in addition to any other type.

参阅 conventionalcommits.org 以获得更多细节。

Breaking Changes

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.

See conventionalcommits.org for more details.

步骤6：变基

提交更改后, 最好使用 git rebase (而不是 git merge) 将您的工作与主代码库同步。

$ git fetch upstream
$ git rebase upstream/master

这可确保您的工作分支具有来自 electron/electron master 分支的最新更改。

Step 6: Rebase

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/master

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

步骤7: 测试

Bug 修复和功能应始终与测试一起进行。 提供了 测试指南 使流程更容易。 看其他测试, 看看它们应该如何结构化也会有帮助。

当提交您的改变到合并代码请求前, 请始终运行完整的测试套件。 运行测试:

$ npm run test

请确保 linter 不报告任何问题, 并且所有测试都通过。 请不要提交失败的修补程序或检查。

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

$ npm run test -match=menu

上述操作只运行与 menu 匹配的规范模块, 这对于那些在测试周期的末尾进行测试的任何人都很有用。

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

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: 推送代码

一旦您的提交准备就绪--通过测试和 linting--将您的工作分支推送到您在 GitHub 上复制的分支, 然后开始开启合并代码请求的过程。

$ git push origin my-branch

Step 8: Push

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: 新建一个合并代码请求

从 GitHub 中, 开启一个新的合并代码请求将为您呈现一个模板，这应填写如下:

<!--
Thank you for your pull request. Please provide a description above and review
the requirements below.
Bug fixes and new features should include tests and possibly benchmarks.
Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTING.md
-->

Step 9: Opening the Pull Request

From within GitHub, opening a new pull request will present you with a template that should be filled out:

<!--
Thank you for your pull request. Please provide a description above and review
the requirements below.
Bug fixes and new features should include tests and possibly benchmarks.
Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTING.md
-->

步骤10: 讨论和更新

您可能会得到反馈或请求更改您的请求。 这是提交过程的重要部分, 所以不要气馁! 有些贡献者可能会立刻签署请求。 其他人可能有详细的评论或反馈。 这是过程的必要部分, 以便评估更改是否正确和必要。

要更改现有的请求, 请对本地分支进行更改, 添加新的提交, 并将这些更改推送到您的分支。 GitHub 将自动更新请求。

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

一些更高级的方法比如使用 git rebase 来管理提交是很有效的, 但这超出本指南的范围。

如果您正在等待某事的答案, 请随时添加评论 ping 向审阅者。 如果您遇到的单词或缩略词似乎不熟悉, 请参阅此 词汇表 。

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.

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

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

步骤11: 执行合并

为了合并代码, 代码合并请求要求必须由至少一个 Electron 代码所有者审查和批准并且通过 CI。 之后, 如果没有其他参与者的异议, 请求可以合并。

恭喜您, 感谢您的贡献!

Step 11: Landing

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!

持续集成测试

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

理想情况下, 代码合并请求将在 CI 的所有平台上通过测试 ("变成绿色")。 这意味着所有测试都通过, 并且没有 linting 错误。 然而，CI 自身的基础设施在特定的平台上或者在"不可靠"的测试下会失败("变红") 的情况并不少见。 必须手动检查每个 CI 故障以确定原因。

Ci 在打开请求时自动启动, 但只有 发布者 才能重新启动 ci 运行。 如果你认为 CI 给出了错误的否定, 请求发布者重新启动测试。

Continuous Integration Testing

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

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 starts automatically when you open a pull request, but only Releasers can restart a CI run. If you believe CI is giving a false negative, ask a Releaser to restart the tests.