Electron Documentation1.7.9

Electron 1.7.9 / Docs / Guides / Electron Versioning

Electron Versioning

A detailed look at our versioning policy and implementation.

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

npm install --save-dev electron

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

npm install --save-dev electron@latest

Version 1.x

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. 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, Stride, Teams, Skype, VS Code, Atom, and 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.

Here is an example of the 1.x strategy:

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.

Version 2.0 and Beyond

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. Strict use of semver
  2. Introduction of semver-compliant -beta tags
  3. Introduction of conventional commit messages
  4. Clearly defined stabilization branches
  5. The master branch is versionless; only stability branches contain version information

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

From 2.0 onward, Electron will follow semver.

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

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

Stabilization Branches

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

Stabilization branches are always either major or minor version lines, and named against the following template $MAJOR-$MINOR-x e.g. 2-0-x.

We allow for multiple stabilization branches to exist simultaneously, and intend to support at least two in parallel at all times, backporting security fixes as necessary.

Older lines will not be supported by GitHub, 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 Releases and Bug Fixes

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 :

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.

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. All new major and minor releases lines begin with a -beta.N tag for N >= 1. At that point, the feature set is locked. That release line admits no further features, and focuses only on security and stability. e.g. 2.0.0-beta.1.
  2. Bug fixes, regression fixes, and security patches can be admitted. Upon doing so, a new beta is released incrementing N. e.g. 2.0.0-beta.2
  3. 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.
  4. 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 accordingly e.g. 2.0.1.

For each major and minor bump, you should expect too 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:

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

Missing Features: Alphas, and Nightly

Our strategy has a few tradeoffs, which for now we feel are appropriate. Most importantly that new features in master may take a while before reaching a stable release line. If you want to try a new feature immediately, you will have to build Electron yourself.

As a future consideration, we may introduce one or both of the following:

Feature Flags

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:

We reconcile flagged code with our versioning strategy as follows:

  1. we do not consider iterating on feature-flagged code in a stability branch; even judicious use of feature flags is not without risk
  2. you may break API contracts in feature-flagged code without bumping the major version. Flagged code does not adhere to semver

Semantic Commits

We seek to increase clarity at all levels of the update and releases process. Starting with 2.0.0 we will require pull requests adhere to the Conventional Commits spec, which can be summarized as follows:

Versionless master


See something that needs fixing? Propose a change to the source file.
Need a different version of the docs? See available versions.
Want something searchable? View all docs on one page