Electron 版本控制

🌐 Electron Versioning

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

从版本 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 规范
2. 遵循语义化版本的 -beta 标签介绍
3. 常规提交信息 介绍
4. 明确的稳定分支
5. main 分支没有版本信息；只有稳定分支包含版本信息

我们将详细介绍 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 补丁版本更新
Chromium 版本更新		修复相关的 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 中允许以下标准语义化版本范围：

🌐 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 版本。
• 使用 ^2.0.0 来处理非中断的、相对稳定 的功能开发，以及安全性和漏洞修复。

第二点的重要之处在于，使用 ^ 的应用仍应能够预期到合理的稳定性。为实现这一点，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. 所有新的主要版本和次要版本系列都以测试版系列开始，用 SemVer 预发布标签 beta.N 表示，例如 2.0.0-beta.1。在第一个测试版之后，后续的测试版必须满足以下所有条件：
   1. 该更改向后兼容 API（允许弃用）
   2. 满足稳定时间表的风险必须很低。
2. 如果在发布版本为测试版时需要进行允许的更改，这些更改将被应用，并且预发布标签会增加，例如 2.0.0-beta.2。
3. 如果某个特定的 Beta 版本被普遍认为是稳定的，它将作为稳定版本重新发布，仅修改版本信息，例如 2.0.0。在第一个稳定版本之后，所有更改必须是向后兼容的错误或安全修复。
4. 如果在版本稳定后需要进行后续的漏洞修复或安全补丁，它们会被应用，并且 patch 版本会递增，例如 2.0.1。

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

🌐 Specifically, the above means:

1. 在测试周期的第 3 周之前承认非破坏性 API 更改是可以的，即使这些更改有可能导致中等程度的副作用。
2. 在大多数测试周期中，接受带有功能标记的更改，只要这些更改不会改变现有的代码路径，是可以的。用户可以在他们的应用中显式启用这些标记。
3. 在测试周期的第三周之后承认任何类型的功能都是👎，没有很好的理由。

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

🌐 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。
• 一个修复漏洞的补丁被合并到主分支，并且可以回溯到发布分支。补丁已应用，并发布了新的测试版 2.0.0-beta.2。
• 该测试版被认为是_总体稳定的_，并且它已作为非测试版重新发布，版本号为 2.0.0。
• 后来，发现了一个零日漏洞，并将修复补丁应用到主分支。我们将该修复补丁回溯到 2-0-x 分支，并发布了 2.0.1。

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

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

向后移植请求进程

🌐 Backport request process

所有受支持的发布分支都将接受外部拉取请求，以回移以前合并到 main 的修复，尽管对于一些较旧的受支持分支，这可能需要逐案处理。所有关于发布分支回移的有争议决定将由 发布工作组 在每周会议中作为议程项目进行解决，会议将在提出回移拉取请求的那周举行。

🌐 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 中是常见的做法，并且在网页开发生态系统中已被广泛认可。在 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:

• 它可以在运行时或构建时启用/禁用；我们不支持基于请求范围的功能开关概念
• 它完全将新旧代码路径分开；为了支持新功能而重构旧代码会 违反 功能开关协议
• 功能发布后，功能标志最终会被删除

语义提交

🌐 Semantic commits

所有拉取请求必须遵循 Conventional Commits 规范，可归纳如下：

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

• 会导致 SemVer 大版本 提升的提交，其正文必须以 BREAKING CHANGE: 开头。
• 会导致 SemVer 次要 版本升级的提交必须以 feat: 开头。
• 会导致 SemVer 修补版本 更新的提交必须以 fix: 开头。

electron/electron 仓库也强制使用 squash 合并，因此你只需要确保你的拉取请求有正确的标题前缀。

🌐 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。
• 发布分支从不合并回 main。
• 发布分支确实在它们的 package.json 中包含正确的版本。
• 一旦为一个重大版本创建了发布分支，main 必须升级到下一个主要版本（即 main 总是作为下一个理论发布分支进行版本控制）。

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

🌐 Historical versioning (Electron 1.X)

Electron 版本 < 2.0 并不符合 SemVer 规范：主版本对应终端用户 API 的变更，次版本对应 Chromium 的主要版本发布，修订版本对应新功能和漏洞修复。虽然这种方式便于开发者合并功能，但对于面向客户的应用开发者而言，这会带来问题。像 Slack、Teams、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, 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.