You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/tutorial/electron-versioning.md
+35-43Lines changed: 35 additions & 43 deletions
Original file line number
Diff line number
Diff line change
@@ -2,43 +2,31 @@
2
2
3
3
> A detailed look at our versioning policy and implementation.
4
4
5
-
As of version 2.0.0, Electron follows [SemVer](#semver). The following command will install the most recent stable build of Electron:
5
+
As of version 2.0.0, Electron follows the [SemVer](#semver) spec. The following command will install the most recent stable build of Electron:
6
6
7
-
```sh
7
+
```sh npm2yarn
8
8
npm install --save-dev electron
9
9
```
10
10
11
11
To update an existing project to use the latest stable version:
12
12
13
-
```sh
13
+
```sh npm2yarn
14
14
npm install --save-dev electron@latest
15
15
```
16
16
17
-
## Version 1.x
18
-
19
-
Electron versions *< 2.0* did not conform to the [SemVer](https://semver.org) 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, 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.
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.
26
-
27
-
## Version 2.0 and Beyond
17
+
## Versioning scheme
28
18
29
19
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.
30
20
31
-
1. Strict use of SemVer
21
+
1. Strict use of the the [SemVer](#semver) spec
32
22
2. Introduction of semver-compliant `-beta` tags
33
23
3. Introduction of [conventional commit messages](https://conventionalcommits.org/)
34
24
4. Well-defined stabilization branches
35
-
5. The `master` branch is versionless; only stabilization branches contain version information
25
+
5. The `main` branch is versionless; only stabilization branches contain version information
36
26
37
27
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.
38
28
39
-
# SemVer
40
-
41
-
From 2.0 onward, Electron will follow SemVer.
29
+
## SemVer
42
30
43
31
Below is a table explicitly mapping types of changes to their corresponding category of SemVer (e.g. Major, Minor, Patch).
44
32
@@ -48,22 +36,25 @@ Below is a table explicitly mapping types of changes to their corresponding cate
48
36
| Node.js major version updates | Node.js minor version updates | Node.js patch version updates |
49
37
| Chromium version updates || fix-related chromium patches |
50
38
39
+
For more information, see the [Semantic Versioning 2.0.0](https://semver.org/) spec.
40
+
51
41
Note that most Chromium updates will be considered breaking. Fixes that can be backported will likely be cherry-picked as patches.
52
42
53
-
# Stabilization Branches
43
+
##Stabilization branches
54
44
55
-
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.
45
+
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`.
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`
49
+
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`.
50
+
51
+
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 Release Timelines](./electron-timelines.md) doc.
60
52
61
-
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.
55
+
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.
65
56
66
-
# Beta Releases and Bug Fixes
57
+
##Beta releases and bug fixes
67
58
68
59
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` :
69
60
@@ -116,36 +107,37 @@ A few examples of how various SemVer ranges will pick up new releases:
116
107
117
108
118
109
119
-
# Missing Features: Alphas
120
-
121
-
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.
122
-
123
-
As a future consideration, we may introduce one or both of the following:
124
-
125
-
* alpha releases that have looser stability constraints to betas; for example it would be allowable to admit new features while a stability channel is in _alpha_
126
-
127
-
# Feature Flags
110
+
## Feature flags
128
111
129
112
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:
130
113
131
114
* it is enabled/disabled either at runtime, or build-time; we do not support the concept of a request-scoped feature flag
132
115
* it completely segments new and old code paths; refactoring old code to support a new feature _violates_ the feature-flag contract
133
116
* feature flags are eventually removed after the feature is released
134
117
135
-
# Semantic Commits
118
+
##Semantic commits
136
119
137
-
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](https://conventionalcommits.org/) spec, which can be summarized as follows:
120
+
All pull requests must adhere to the [Conventional Commits](https://conventionalcommits.org/) spec, which can be summarized as follows:
138
121
139
122
* Commits that would result in a SemVer **major** bump must start their body with `BREAKING CHANGE:`.
140
123
* Commits that would result in a SemVer **minor** bump must start with `feat:`.
141
124
* Commits that would result in a SemVer **patch** bump must start with `fix:`.
142
125
143
-
* We allow squashing of commits, provided that the squashed message adheres to the above message format.
144
-
* It is acceptable for some commits in a pull request to not include a semantic prefix, as long as the pull request title contains a meaningful encompassing semantic message.
126
+
The `electron/electron` repository also enforces squash merging, so you only need to make sure that your pull request has the correct title prefix.
127
+
128
+
## Versioned `main` branch
129
+
130
+
* The `main` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json`.
131
+
* Release branches are never merged back to `main`.
132
+
* Release branches _do_ contain the correct version in their `package.json`.
133
+
* 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).
134
+
135
+
## Historical versioning (Electron 1.X)
145
136
146
-
# Versioned `master`
137
+
Electron versions *< 2.0* did not conform to the [SemVer](https://semver.org) 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.
147
138
148
-
* The `master` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json`
149
-
* Release branches are never merged back to master
150
-
* Release branches _do_ contain the correct version in their `package.json`
151
-
* As soon as a release branch is cut for a major, master must be bumped to the next major. I.e. `master` is always versioned as the next theoretical release branch
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.
0 commit comments