Electron 版本控制

¥Electron Versioning

详细了解我们的版本控制政策和实现。

¥A detailed look at our versioning policy and implementation.

从 2.0.0 版本开始，Electron 遵循 SemVer 规范。以下命令将安装 Electron 的最新稳定版本：

¥As of version 2.0.0, Electron follows the SemVer spec. The following command will install the most recent stable build of Electron:

npm

npm install --save-dev electron

Yarn

yarn add --dev electron

要更新现有项目以使用最新的稳定版本：

¥To update an existing project to use the latest stable version:

npm

npm install --save-dev electron@latest

Yarn

yarn add --dev electron@latest

版本控制方案

¥Versioning scheme

我们的 1.x 策略有几个重大变化，概述如下。每个更改都是为了满足开发者/维护人员和应用开发者的需求和优先级。

¥There are several major changes from our 1.x strategy outlined below. Each change is intended to satisfy the needs and priorities of developers/maintainers and app developers.

1. 严格使用 SemVer 规范

   ¥Strict use of the SemVer spec

2. 引入符合 semver 的 -beta 标签

   ¥Introduction of semver-compliant -beta tags

3. 常规提交消息 简介

   ¥Introduction of conventional commit messages

4. 明确的稳定分支

   ¥Well-defined stabilization branches

5. main 分支是无版本的；只有稳定分支包含版本信息

   ¥The main branch is versionless; only stabilization branches contain version information

我们将详细介绍 git 分支的工作原理、npm 标记的工作原理、开发者应该看到的内容以及如何向后移植更改。

¥We will cover in detail how git branching works, how npm tagging works, what developers should expect to see, and how one can backport changes.

SemVer

下面是一个表，将更改类型显式映射到其相应的 SemVer 类别（例如，主要、次要、补丁）。

¥Below is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).

主要版本增量	小版本增量	补丁版本增量
Electron 断裂 API 更改	Electron 不间断 API 更改	Electron 错误修复
Node.js 主要版本更新	Node.js 小版本更新	Node.js 补丁版本更新
Chrom 版本更新		修复相关的 chromium 补丁

有关详细信息，请参阅 语义版本控制 2.0.0 规范。

¥For more information, see the Semantic Versioning 2.0.0 spec.

请注意，大多数 Chromium 更新将被视为破坏。可以向后移植的修复可能会被挑选为补丁。

¥Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.

稳定分支

¥Stabilization branches

稳定分支是与 main 并行运行的分支，仅接受与安全或稳定性相关的精选提交。这些分支永远不会合并回 main。

¥Stabilization branches are branches that run parallel to main, taking in only cherry-picked commits that are related to security or stability. These branches are never merged back to main.

从 Electron 8 开始，稳定分支始终是主要版本线，并根据以下模板 $MAJOR-x-y 命名，例如 8-x-y。在此之前，我们使用次要版本行并将其命名为 $MAJOR-$MINOR-x，例如 2-0-x。

¥Since Electron 8, stabilization branches are always major version lines, and named against the following template $MAJOR-x-y e.g. 8-x-y. Prior to that we used minor version lines and named them as $MAJOR-$MINOR-x e.g. 2-0-x.

我们允许多个稳定分支同时存在，每个支持的版本一个。有关受支持版本的更多详细信息，请参阅我们的 Electron 发布 文档。

¥We allow for multiple stabilization branches to exist simultaneously, one for each supported version. For more details on which versions are supported, see our Electron Releases doc.

Electron 项目不会支持较旧的产品线，但其他群组可以自行获得所有权并向后移植稳定性和安全修复程序。我们不鼓励这样做，但我们认识到这会让许多应用开发者的生活变得更轻松。

¥Older lines will not be supported by the Electron project, but other groups can take ownership and backport stability and security fixes on their own. We discourage this, but recognize that it makes life easier for many app developers.

Beta 版本和错误修复

¥Beta releases and bug fixes

开发者想知道哪些版本可以安全使用。即使看似无害的功能也可能在复杂的应用中引入回归。同时，锁定到固定版本是危险的，因为你忽略了自你的版本以来可能出现的安全补丁和错误修复。我们的目标是在 package.json 中允许以下标准 semver 范围：

¥Developers want to know which releases are safe to use. Even seemingly innocent features can introduce regressions in complex applications. At the same time, locking to a fixed version is dangerous because you’re ignoring security patches and bug fixes that may have come out since your version. Our goal is to allow the following standard semver ranges in package.json :

• 使用 ~2.0.0 仅允许对 2.0.0 版本进行稳定性或安全相关的修复。

  ¥Use ~2.0.0 to admit only stability or security related fixes to your 2.0.0 release.

• 使用 ^2.0.0 来承认非破坏性的、相当稳定的功能工作以及安全性和错误修复。

  ¥Use ^2.0.0 to admit non-breaking reasonably stable feature work as well as security and bug fixes.

第二点重要的是，使用 ^ 的应用仍然应该能够获得合理的稳定性水平。为了实现这一点，SemVer 允许使用预发布标识符来指示特定版本尚不安全或稳定。

¥What’s important about the second point is that apps using ^ should still be able to expect a reasonable level of stability. To accomplish this, SemVer allows for a pre-release identifier to indicate a particular version is not yet safe or stable.

无论你选择什么，你都必须定期升级 package.json 中的版本，因为重大更改是 Chromium 生命中的事实。

¥Whatever you choose, you will periodically have to bump the version in your package.json as breaking changes are a fact of Chromium life.

进程如下：

¥The process is as follows:

1. 所有新的主要和次要发行版均以 Beta 系列开头，由 beta.N 的 SemVer 预发行标签指示，例如 2.0.0-beta.1。第一个 Beta 版发布后，后续 Beta 版发布必须满足以下所有条件：

   ¥All new major and minor releases lines begin with a beta series indicated by SemVer prerelease tags of beta.N, e.g. 2.0.0-beta.1. After the first beta, subsequent beta releases must meet all of the following conditions:

   1. 该更改向后兼容 API（允许弃用）

      ¥The change is backwards API-compatible (deprecations are allowed)

   2. 满足稳定时间表的风险必须很低。

      ¥The risk to meeting our stability timeline must be low.

2. 如果在测试版发布后需要进行允许的更改，则会应用这些更改并递增预发布标签，例如 2.0.0-beta.2。

   ¥If allowed changes need to be made once a release is beta, they are applied and the prerelease tag is incremented, e.g. 2.0.0-beta.2.

3. 如果某个特定的测试版本通常被认为是稳定的，它将作为稳定版本重新发布，仅更改版本信息。例如 2.0.0。在第一次稳定之后，所有更改都必须是向后兼容的错误或安全修复。

   ¥If a particular beta release is generally regarded as stable, it will be re-released as a stable build, changing only the version information. e.g. 2.0.0. After the first stable, all changes must be backwards-compatible bug or security fixes.

4. 如果在版本稳定后需要进行未来的错误修复或安全补丁，则会应用它们并增加补丁版本，例如 2.0.1。

   ¥If future bug fixes or security patches need to be made once a release is stable, they are applied and the patch version is incremented e.g. 2.0.1.

具体来说，上面的意思是：

¥Specifically, the above means:

1. 在测试周期的第 3 周之前承认非破坏性 API 更改是可以的，即使这些更改有可能导致中等程度的副作用。

   ¥Admitting non-breaking-API changes before Week 3 in the beta cycle is okay, even if those changes have the potential to cause moderate side-effects.

2. 在测试周期的大多数时间点上，承认功能标记的更改（这些更改不会改变现有的代码路径）是可以的。用户可以在其应用中显式启用这些标志。

   ¥Admitting feature-flagged changes, that do not otherwise alter existing code paths, at most points in the beta cycle is okay. Users can explicitly enable those flags in their apps.

3. 在测试周期的第三周之后承认任何类型的功能都是👎，没有很好的理由。

   ¥Admitting features of any sort after Week 3 in the beta cycle is 👎 without a very good reason.

对于每个主要和次要的颠簸，你应该会看到类似以下内容：

¥For each major and minor bump, you should expect to see something like the following:

2.0.0-beta.1
2.0.0-beta.2
2.0.0-beta.3
2.0.0
2.0.1
2.0.2

图片中的生命周期示例：

¥An example lifecycle in pictures:

• 创建了一个新的发布分支，其中包含最新的功能集。它被发布为 2.0.0-beta.1。

  ¥A new release branch is created that includes the latest set of features. It is published as 2.0.0-beta.1.

• master 中出现了错误修复，可以向后移植到发布分支。该补丁已应用，新的测试版已发布为 2.0.0-beta.2。

  ¥A bug fix comes into master that can be backported to the release branch. The patch is applied, and a new beta is published as 2.0.0-beta.2.

• 该测试版被认为总体稳定，并在 2.0.0 下作为非测试版再次发布。

  ¥The beta is considered generally stable and it is published again as a non-beta under 2.0.0.

• 后来，一个零日漏洞被揭露，并对 master 进行了修复。我们将修复程序向后移植到 2-0-x 系列并发布 2.0.1。

  ¥Later, a zero-day exploit is revealed and a fix is applied to master. We backport the fix to the 2-0-x line and release 2.0.1.

以下是不同 SemVer 系列如何获取新版本的几个示例：

¥A few examples of how various SemVer ranges will pick up new releases:

向后移植请求进程

¥Backport request process

所有受支持的发行版都将接受外部拉取请求，以向后移植先前合并到 main 的修复程序，尽管对于某些较旧的受支持版来说，这可能需要根据具体情况进行。所有关于发布线向后移植的有争议的决定都将由 发布工作组 作为议程项目在提出向后移植 PR 的一周的每周会议上解决。

¥All supported release lines will accept external pull requests to backport fixes previously merged to main, though this may be on a case-by-case basis for some older supported lines. All contested decisions around release line backports will be resolved by the Releases Working Group as an agenda item at their weekly meeting the week the backport PR is raised.

功能标志

¥Feature flags

功能标志是 Chromium 中的常见做法，并且在 Web 开发生态系统中已经很成熟。在 Electron 的上下文中，功能标志或软分支必须具有以下属性：

¥Feature flags are a common practice in Chromium, and are well-established in the web-development ecosystem. In the context of Electron, a feature flag or soft branch must have the following properties:

• 它可以在运行时或构建时启用/禁用；我们不支持请求范围的功能标志的概念

  ¥it is enabled/disabled either at runtime, or build-time; we do not support the concept of a request-scoped feature flag

• 它完全分割新旧代码路径；重构旧代码以支持新功能违反了功能标志契约

  ¥it completely segments new and old code paths; refactoring old code to support a new feature violates the feature-flag contract

• 功能发布后，功能标志最终会被删除

  ¥feature flags are eventually removed after the feature is released

语义提交

¥Semantic commits

所有拉取请求都必须遵守 常规提交 规范，该规范可概括如下：

¥All pull requests must adhere to the Conventional Commits spec, which can be summarized as follows:

• 会导致 SemVer 重大变更的提交必须以 BREAKING CHANGE: 开头。

  ¥Commits that would result in a SemVer major bump must start their body with BREAKING CHANGE:.

• 会导致 SemVer 小幅提升的提交必须以 feat: 开始。

  ¥Commits that would result in a SemVer minor bump must start with feat:.

• 导致 SemVer 补丁更新的提交必须以 fix: 开始。

  ¥Commits that would result in a SemVer patch bump must start with fix:.

electron/electron 存储库还强制执行压缩合并，因此你只需确保你的拉取请求具有正确的标题前缀。

¥The electron/electron repository also enforces squash merging, so you only need to make sure that your pull request has the correct title prefix.

版本化 main 分支

¥Versioned main branch

• main 分支将始终包含其 package.json 中的下一个主要版本 X.0.0-nightly.DATE。

  ¥The main branch will always contain the next major version X.0.0-nightly.DATE in its package.json.

• 发布分支永远不会合并回 main。

  ¥Release branches are never merged back to main.

• 发布分支确实在其 package.json 中包含正确的版本。

  ¥Release branches do contain the correct version in their package.json.

• 一旦某个主要版本分支被删除，main 就必须跳到下一个主要版本（即 main 始终被版本化为下一个理论上的发行分支）。

  ¥As soon as a release branch is cut for a major, main must be bumped to the next major (i.e. main is always versioned as the next theoretical release branch).

历史版本控制 (Electron 1.X)

¥Historical versioning (Electron 1.X)

Electron 版本 < 2.0 不符合 SemVer 规范：主要版本对应于终端用户 API 更改，次要版本对应于 Chromium 主要版本，补丁版本对应于新功能和错误修复。虽然方便开发者合并功能，但它给面向客户端的应用的开发者带来了问题。Slack、Teams、Skype、VS Code 和 GitHub Desktop 等主要应用的 QA 测试周期可能很长，而稳定性是人们非常期望的结果。在尝试吸收错误修复的同时采用新功能存在很高的风险。

¥Electron versions < 2.0 did not conform to the SemVer spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Teams, Skype, VS Code, and GitHub Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.

以下是 1.x 策略的示例：

¥Here is an example of the 1.x strategy:

使用 1.8.1 开发的应用无法在不吸收 1.8.2 功能或向后移植修复程序并维护新版本的情况下修复 1.8.3 错误。

¥An app developed with 1.8.1 cannot take the 1.8.3 bug fix without either absorbing the 1.8.2 feature, or by backporting the fix and maintaining a new release line.