From cc80930e2b2c71615013f4e12b7cffcd1fc306ff Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 23 Aug 2017 08:54:23 -0700 Subject: [PATCH 01/12] document prereleases --- docs/tutorial/electron-versioning.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 3f6c9ef90d43..f953b8606d26 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -4,7 +4,7 @@ If you've been using Node and npm for a while, you are probably aware of [Semant ## Overview of Semantic Versioning -Semantic versions are always made up of three numbers: +Semantic versions are always made up of (at least) three numbers: ``` major.minor.patch @@ -22,10 +22,13 @@ A simple mnemonic for remembering this scheme is as follows: breaking.feature.fix ``` +Unstable versions may also have a _pre-release identifier_. See +[Prereleases](#prereleases). + ## Electron Versioning Due to its dependency on Node and Chromium, it is not possible for the Electron -project to adhere to a SemVer policy. **You should therefore always +project to adhere to a strict SemVer policy. **You should therefore always reference a specific version of Electron.** Electron version numbers are bumped using the following rules: @@ -52,4 +55,24 @@ Alternatively, you can use the `~` prefix in your SemVer range, like `~1.6.2`. This will lock your major and minor version, but allow new patch versions to be installed. +## Prereleases + +Starting at version 1.8, unstable releases of Electron have a suffix called a +[pre-release identifier] appended to their version number, +e.g. `1.8.0-beta.0`. A version may have many prereleases before it is +considered stable, e.g. `1.8.0-beta.0`, `1.8.0-beta.1`, and eventually `1.8.0`. + +When major, minor, and patch are equal, a pre-release version has lower +precedence than a [normal version], e.g. `1.8.0-beta.0 < 1.8.0`. This is +convenient because it allows you to use a range like `^1.8.0` and know +that it will never match an unstable pre-release version. + +The `latest` and `next` [npm dist tags] are also used: + +- `npm install electron@latest` will install the latest _stable_ version. +- `npm install electron@next` will install the very latest _unstable_ version. + [Semantic Versioning]: http://semver.org +[pre-release identifier]: http://semver.org/#spec-item-9 +[npm dist tags]: https://docs.npmjs.com/cli/dist-tag +[normal version]: http://semver.org/#spec-item-2 From fe7c827e30812f57edb0b3d96f460444dc9af30b Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 23 Aug 2017 13:57:28 -0700 Subject: [PATCH 02/12] remove section on semver, as electron does not fit its mold --- docs/tutorial/electron-versioning.md | 31 +++------------------------- 1 file changed, 3 insertions(+), 28 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index f953b8606d26..bf8f68dfb863 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -2,34 +2,9 @@ If you've been using Node and npm for a while, you are probably aware of [Semantic Versioning], or SemVer for short. It's a convention for specifying version numbers for software that helps communicate intentions to the users of your software. -## Overview of Semantic Versioning - -Semantic versions are always made up of (at least) three numbers: - -``` -major.minor.patch -``` - -Semantic version numbers are bumped (incremented) using the following rules: - -* **Major** is for changes that break backwards compatibility. -* **Minor** is for new features that don't break backwards compatibility. -* **Patch** is for bug fixes and other minor changes. - -A simple mnemonic for remembering this scheme is as follows: - -``` -breaking.feature.fix -``` - -Unstable versions may also have a _pre-release identifier_. See -[Prereleases](#prereleases). - -## Electron Versioning - Due to its dependency on Node and Chromium, it is not possible for the Electron -project to adhere to a strict SemVer policy. **You should therefore always -reference a specific version of Electron.** +project to adhere to a strict [Semantic Versioning] policy. **You should +therefore always reference a specific version of Electron.** Electron version numbers are bumped using the following rules: @@ -75,4 +50,4 @@ The `latest` and `next` [npm dist tags] are also used: [Semantic Versioning]: http://semver.org [pre-release identifier]: http://semver.org/#spec-item-9 [npm dist tags]: https://docs.npmjs.com/cli/dist-tag -[normal version]: http://semver.org/#spec-item-2 +[normal version]: http://semver.org/#spec-item-2 \ No newline at end of file From cd411a5c36808547a4c24b32bd9ad9c5459d8a5e Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 23 Aug 2017 14:11:20 -0700 Subject: [PATCH 03/12] document how we define stable --- docs/tutorial/electron-versioning.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index bf8f68dfb863..70b97f878603 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -47,6 +47,27 @@ The `latest` and `next` [npm dist tags] are also used: - `npm install electron@latest` will install the latest _stable_ version. - `npm install electron@next` will install the very latest _unstable_ version. +## Stable Releases + +In general, a version is considered stable after its most recent +[prerelease](#prereleases) has been out for two weeks and any significant bugs +reported against it have been fixed. Note that versions are not promoted on a +set schedule, and timing can fluctuate per release. + +We recommend using the following command to ensure you're using a stable +version of Electron: + +```sh +npm install electron --save-exact --save-dev +``` + +If you have an existing Electron app and want to update it to use the latest +stable version of `electron`, use the `@latest` identifier: + +```sh +npm install electron@latest --save-exact --save-dev +``` + [Semantic Versioning]: http://semver.org [pre-release identifier]: http://semver.org/#spec-item-9 [npm dist tags]: https://docs.npmjs.com/cli/dist-tag From d51a8accee548f866dd221dc982127f314dc42d0 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 23 Aug 2017 14:14:59 -0700 Subject: [PATCH 04/12] tweak versioning doc --- docs/tutorial/electron-versioning.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 70b97f878603..eb1edb4d06d7 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -4,17 +4,18 @@ If you've been using Node and npm for a while, you are probably aware of [Semant Due to its dependency on Node and Chromium, it is not possible for the Electron project to adhere to a strict [Semantic Versioning] policy. **You should -therefore always reference a specific version of Electron.** +therefore always reference a specific version of Electron** in your +`package.json` file. Electron version numbers are bumped using the following rules: * **Major** is for breaking changes in Electron's API. If you upgrade from `0.37.0` to `1.0.0`, you will have to make changes to your app. * **Minor** is for major Chrome and minor Node upgrades, or significant Electron - changes. If you upgrade from `1.5.0` to `1.6.0`, your app is supposed to + changes. If you upgrade from `1.5.0` to `1.6.0`, your app should still work, but you might have to work around small changes. * **Patch** is for new features and bug fixes. If you upgrade from `1.6.2` to - `1.6.3`, your app will continue to work as-is. + `1.6.3`, your app should continue to work as-is. We recommend that you set a fixed version when installing Electron from npm: @@ -22,9 +23,10 @@ We recommend that you set a fixed version when installing Electron from npm: npm install electron --save-exact --save-dev ``` -The `--save-exact` flag will add `electron` to your `package.json` file without -using a `^` or `~`, e.g. `1.6.2` instead of `^1.6.2`. This practice ensures that -all upgrades of Electron are a manual operation made by you, the developer. +The `--save-exact` flag will add `electron` to your `package.json` file _without +a range identifier_ like `^` or `~`, e.g. `1.6.2` instead of `^1.6.2`. This +practice ensures that all upgrades of Electron are a manual operation made by +you, the developer. Alternatively, you can use the `~` prefix in your SemVer range, like `~1.6.2`. This will lock your major and minor version, but allow new patch versions to From 9f55e162a38bc9ff933efe12c8ffa563d57da107 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Mon, 28 Aug 2017 14:45:55 -0400 Subject: [PATCH 05/12] add section on dist-tags --- docs/tutorial/electron-versioning.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index eb1edb4d06d7..4574485c1662 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -44,10 +44,21 @@ precedence than a [normal version], e.g. `1.8.0-beta.0 < 1.8.0`. This is convenient because it allows you to use a range like `^1.8.0` and know that it will never match an unstable pre-release version. -The `latest` and `next` [npm dist tags] are also used: +## Distribution tags + +Electron supports three streams of development versions, each of which is identified by using an [npm dist tag]: + +- **`prev`**: denotes the version of Electron that is _one minor_ behind the `latest +- **`latest`**: denotes the _latest stable_ version +- **`next`**: denotes the _upcoming (maybe unstable)_ version + +A `dist-tag` can be used when installing Electron as a reference to a version instead of using a specific version number: + +``` +npm install electron@ +``` +**Note:** if unspecified, `latest` will be used. -- `npm install electron@latest` will install the latest _stable_ version. -- `npm install electron@next` will install the very latest _unstable_ version. ## Stable Releases @@ -72,5 +83,5 @@ npm install electron@latest --save-exact --save-dev [Semantic Versioning]: http://semver.org [pre-release identifier]: http://semver.org/#spec-item-9 -[npm dist tags]: https://docs.npmjs.com/cli/dist-tag +[npm dist tag]: https://docs.npmjs.com/cli/dist-tag [normal version]: http://semver.org/#spec-item-2 \ No newline at end of file From ba6f01a10987e8a4faac6c72e28e9758a16d6ad5 Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Mon, 28 Aug 2017 12:17:00 -0700 Subject: [PATCH 06/12] add missing backtick --- docs/tutorial/electron-versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 4574485c1662..e0729298bb8a 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -48,7 +48,7 @@ that it will never match an unstable pre-release version. Electron supports three streams of development versions, each of which is identified by using an [npm dist tag]: -- **`prev`**: denotes the version of Electron that is _one minor_ behind the `latest +- **`prev`**: denotes the version of Electron that is _one minor_ behind the `latest` - **`latest`**: denotes the _latest stable_ version - **`next`**: denotes the _upcoming (maybe unstable)_ version @@ -84,4 +84,4 @@ npm install electron@latest --save-exact --save-dev [Semantic Versioning]: http://semver.org [pre-release identifier]: http://semver.org/#spec-item-9 [npm dist tag]: https://docs.npmjs.com/cli/dist-tag -[normal version]: http://semver.org/#spec-item-2 \ No newline at end of file +[normal version]: http://semver.org/#spec-item-2 From 44572dce7d08f65e7e848281592d7e7d9e7a867b Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Tue, 5 Sep 2017 10:38:30 -0700 Subject: [PATCH 07/12] add sh to code block --- docs/tutorial/electron-versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index e0729298bb8a..58c2ca5efe81 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -54,11 +54,11 @@ Electron supports three streams of development versions, each of which is identi A `dist-tag` can be used when installing Electron as a reference to a version instead of using a specific version number: -``` +```sh npm install electron@ ``` -**Note:** if unspecified, `latest` will be used. +**Note:** if unspecified, `latest` will be used. ## Stable Releases From 3a0de7e24a4f1264965723b25466aa6b17742241 Mon Sep 17 00:00:00 2001 From: Daniel Imms Date: Wed, 20 Sep 2017 21:44:12 +0900 Subject: [PATCH 08/12] New release schedule proposal --- docs/images/tutorial-release-schedule.svg | 97 ++++++++++++++++ docs/tutorial/electron-versioning.md | 134 +++++++++++----------- 2 files changed, 167 insertions(+), 64 deletions(-) create mode 100644 docs/images/tutorial-release-schedule.svg diff --git a/docs/images/tutorial-release-schedule.svg b/docs/images/tutorial-release-schedule.svg new file mode 100644 index 000000000000..6fa653916789 --- /dev/null +++ b/docs/images/tutorial-release-schedule.svg @@ -0,0 +1,97 @@ + + + + + + + + master + + + + + 2.0 + + v2.0.0-beta0 + + v2.0.0 + + + + + 2.1 + + v2.1.0-beta0 + + v2.1.0-beta1 + + v2.1.0 + + + + + 3.0 + + v3.0.0-beta0 + + v3.0.0 + + + + + bug fix + + + + + bug fix + + + + + bug fix + + + + + bug fix + + + + + bug fix + + + + + + feature + + + + feature + + + + feature + + + + + chromiumupdate + + + + ~1 week + + + + ~1 week + + + + ~1 week + + + + \ No newline at end of file diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 58c2ca5efe81..c69217d1281c 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -1,87 +1,93 @@ # Electron Versioning +## Overview of Semantic Versioning + If you've been using Node and npm for a while, you are probably aware of [Semantic Versioning], or SemVer for short. It's a convention for specifying version numbers for software that helps communicate intentions to the users of your software. -Due to its dependency on Node and Chromium, it is not possible for the Electron -project to adhere to a strict [Semantic Versioning] policy. **You should -therefore always reference a specific version of Electron** in your -`package.json` file. +Semantic versions are always made up of three numbers: -Electron version numbers are bumped using the following rules: - -* **Major** is for breaking changes in Electron's API. If you upgrade from `0.37.0` - to `1.0.0`, you will have to make changes to your app. -* **Minor** is for major Chrome and minor Node upgrades, or significant Electron - changes. If you upgrade from `1.5.0` to `1.6.0`, your app should - still work, but you might have to work around small changes. -* **Patch** is for new features and bug fixes. If you upgrade from `1.6.2` to - `1.6.3`, your app should continue to work as-is. - -We recommend that you set a fixed version when installing Electron from npm: - -```sh -npm install electron --save-exact --save-dev +``` +major.minor.patch ``` -The `--save-exact` flag will add `electron` to your `package.json` file _without -a range identifier_ like `^` or `~`, e.g. `1.6.2` instead of `^1.6.2`. This -practice ensures that all upgrades of Electron are a manual operation made by -you, the developer. +Semantic version numbers are bumped (incremented) using the following rules: -Alternatively, you can use the `~` prefix in your SemVer range, like `~1.6.2`. -This will lock your major and minor version, but allow new patch versions to -be installed. +* **Major** is for changes that break backwards compatibility. +* **Minor** is for new features that don't break backwards compatibility. +* **Patch** is for bug fixes and other minor changes. -## Prereleases +A simple mnemonic for remembering this scheme is as follows: -Starting at version 1.8, unstable releases of Electron have a suffix called a -[pre-release identifier] appended to their version number, -e.g. `1.8.0-beta.0`. A version may have many prereleases before it is -considered stable, e.g. `1.8.0-beta.0`, `1.8.0-beta.1`, and eventually `1.8.0`. - -When major, minor, and patch are equal, a pre-release version has lower -precedence than a [normal version], e.g. `1.8.0-beta.0 < 1.8.0`. This is -convenient because it allows you to use a range like `^1.8.0` and know -that it will never match an unstable pre-release version. - -## Distribution tags - -Electron supports three streams of development versions, each of which is identified by using an [npm dist tag]: - -- **`prev`**: denotes the version of Electron that is _one minor_ behind the `latest` -- **`latest`**: denotes the _latest stable_ version -- **`next`**: denotes the _upcoming (maybe unstable)_ version - -A `dist-tag` can be used when installing Electron as a reference to a version instead of using a specific version number: - -```sh -npm install electron@ +``` +breaking.feature.fix ``` -**Note:** if unspecified, `latest` will be used. +## Before Version 2 -## Stable Releases +Before version 2 of Electron we didn't follow SemVer, instead the following was used: -In general, a version is considered stable after its most recent -[prerelease](#prereleases) has been out for two weeks and any significant bugs -reported against it have been fixed. Note that versions are not promoted on a -set schedule, and timing can fluctuate per release. +- **Major**: Breaking changes to Electron's API +- **Minor**: Major Chrome, minor node or "significant" Electron changes +- **Patch**: New features and bug fixes -We recommend using the following command to ensure you're using a stable -version of Electron: +This system had a number of drawbacks, such as: + +- New bugs could be introduced into a new patch version because patch versions added features +- It didn't follow SemVer so it could confuse consumers +- It wasn't clear what the differences between stable and beta builds were +- The lack of a formalized stabilization process and release schedule lead to sporadic releases and betas that could last several months + +## Version 2 and Beyond + +From version 2, Electron will attempt to adhere to SemVer and follow a release schedule and stabilization process similar to that of Chromium's that addresses some of the issues some Electron apps were experiencing. + +*Some of the numbers below may change after a few versions.* + +### Version Change Rules + +In order to reduce ambiguity in what changes between releases, Electron is going to attempt to align to SemVer as much as possible. Here are the general rules that will be followed: + +| Type of change | Version increase +|---|--- +| Chromium version update | Major +| Node *major* version update | Major +| Node *minor* version update | Minor +| Electron breaking API change | Major +| Electron non-breaking API change | Minor +| Electron bug fix | Patch +| Anything sufficiently "risky"\* | Major + +\* The idea here is to attempt to mitigate regressions in minor and patch versions so applications can update as easily as possible. An example of a risky change is changing the way that builds are linked. + +Because SemVer is followed, it's recommended that you lock your electron dependency to the minor version using the `~` annotation. This will allow new patch versions (bug fixes) to be updated automatically. + +### The Release Schedule + +![](../images/tutorial-release-schedule.svg) + +Here are some important points to call out: + +- A new release is performed approximately weekly +- Minor versions are branched off of master for stabilization +- The stabilization period is approximately weekly +- Important bug fixes are cherry picked to stabilization branches after landing in master +- Features are not cherry picked, a minor version should only get *more stable* with its patch versions +- There is little difference in the release schedule between a major and minor release, other than the risk/effort it may take for third parties to adopt +- Chromium updates will be performed as fast as the team can manage, in an ideal world this would happen every 6 weeks to align with [Chromium's release schedule][Chromium release] +- Excluding exceptional circumstances, only the previous stable build will get backported bug fixes. + +### The Beta Process + +Electron relies on its consumers getting involved in stabilization. The short target stabilization period and rapid release cadence was designed to shipping security and bug fixes out fast and to encourage the automation of testing. + +You can install the beta by specifying the `beta` dist tag when installing via npm: -```sh -npm install electron --save-exact --save-dev ``` - -If you have an existing Electron app and want to update it to use the latest -stable version of `electron`, use the `@latest` identifier: - -```sh -npm install electron@latest --save-exact --save-dev +npm install electron@beta ``` [Semantic Versioning]: http://semver.org [pre-release identifier]: http://semver.org/#spec-item-9 [npm dist tag]: https://docs.npmjs.com/cli/dist-tag [normal version]: http://semver.org/#spec-item-2 +[Chromium release]: https://www.chromium.org/developers/calendar \ No newline at end of file From b77fe4ca127723bfee5c094d195de83c61ddef6b Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Wed, 4 Oct 2017 12:41:12 -0700 Subject: [PATCH 09/12] add more details to versioning docs --- docs/tutorial/electron-versioning.md | 61 ++++++++++++++++++++-------- docs/tutorial/installation.md | 7 ++-- 2 files changed, 47 insertions(+), 21 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index c69217d1281c..0d7d86c0b1ba 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -39,13 +39,12 @@ This system had a number of drawbacks, such as: ## Version 2 and Beyond -From version 2, Electron will attempt to adhere to SemVer and follow a release schedule and stabilization process similar to that of Chromium's that addresses some of the issues some Electron apps were experiencing. - -*Some of the numbers below may change after a few versions.* +From version 2.0.0, Electron will attempt to adhere to SemVer and follow a +release schedule and stabilization process similar to that of Chromium. ### Version Change Rules -In order to reduce ambiguity in what changes between releases, Electron is going to attempt to align to SemVer as much as possible. Here are the general rules that will be followed: +Here are the general rules that apply when releasing new versions: | Type of change | Version increase |---|--- @@ -57,30 +56,58 @@ In order to reduce ambiguity in what changes between releases, Electron is going | Electron bug fix | Patch | Anything sufficiently "risky"\* | Major -\* The idea here is to attempt to mitigate regressions in minor and patch versions so applications can update as easily as possible. An example of a risky change is changing the way that builds are linked. +When you install an npm module with the `--save` or `--save-dev` flags, it +will be prefixed with a caret `^` in package.json: + +```json +{ + "devDependencies": { + "electron": "^2.0.0" + } +} +``` + +The [caret semver range](https://docs.npmjs.com/misc/semver#caret-ranges-123-025-004) +allows minor- and patch-level changes to be installed, i.e. non-breaking +features and bug fixes. + +Alternatively, a more conservative approach is to use the +[tilde semver range](https://docs.npmjs.com/misc/semver#tilde-ranges-123-12-1) +`~`, which will only allow patch-level upgrades, i.e. bug fixes. -Because SemVer is followed, it's recommended that you lock your electron dependency to the minor version using the `~` annotation. This will allow new patch versions (bug fixes) to be updated automatically. ### The Release Schedule -![](../images/tutorial-release-schedule.svg) +**Note: The schedule outlined here is _aspirational_. We are not yet cutting +releases at a weekly cadence, but we hope to get there eventually.** + + Here are some important points to call out: -- A new release is performed approximately weekly -- Minor versions are branched off of master for stabilization -- The stabilization period is approximately weekly -- Important bug fixes are cherry picked to stabilization branches after landing in master -- Features are not cherry picked, a minor version should only get *more stable* with its patch versions -- There is little difference in the release schedule between a major and minor release, other than the risk/effort it may take for third parties to adopt -- Chromium updates will be performed as fast as the team can manage, in an ideal world this would happen every 6 weeks to align with [Chromium's release schedule][Chromium release] -- Excluding exceptional circumstances, only the previous stable build will get backported bug fixes. +- A new release is performed approximately weekly. +- Minor versions are branched off of master for stabilization. +- The stabilization period is approximately weekly. +- Important bug fixes are cherry-picked to stabilization branches after landing + in master. +- Features are not cherry picked; a minor version should only get *more stable* + with its patch versions. +- There is little difference in the release schedule between a major and minor + release, other than the risk/effort it may take for third parties to adopt +- Chromium updates will be performed as fast as the team can manage. In an ideal + world this would happen every 6 weeks to align with + [Chromium's release schedule][Chromium release]. +- Excluding exceptional circumstances, only the previous stable build will + get backported bug fixes. ### The Beta Process -Electron relies on its consumers getting involved in stabilization. The short target stabilization period and rapid release cadence was designed to shipping security and bug fixes out fast and to encourage the automation of testing. +Electron relies on its consumers getting involved in stabilization. The short +target stabilization period and rapid release cadence was designed for shipping +security and bug fixes out fast and to encourage the automation of testing. -You can install the beta by specifying the `beta` dist tag when installing via npm: +You can install the beta by specifying the `beta` dist tag when installing via +npm: ``` npm install electron@beta diff --git a/docs/tutorial/installation.md b/docs/tutorial/installation.md index 91ad7cff0a26..b53a9064f922 100644 --- a/docs/tutorial/installation.md +++ b/docs/tutorial/installation.md @@ -7,12 +7,11 @@ The preferred method is to install Electron as a development dependency in your app: ```sh -npm install electron --save-dev --save-exact +npm install electron --save-dev ``` -The `--save-exact` flag is recommended as Electron does not follow semantic -versioning. See the -[versioning doc](https://electron.atom.io/docs/tutorial/electron-versioning/) +See the +[Electron versioning doc](https://electron.atom.io/docs/tutorial/electron-versioning/) for info on how to manage Electron versions in your apps. ## Global Installation From f81e4ec972592cca595fe1c32c235552e701ea7c Mon Sep 17 00:00:00 2001 From: Zeke Sikelianos Date: Thu, 5 Oct 2017 10:52:38 -0700 Subject: [PATCH 10/12] order change reasons major, minor, patch --- docs/tutorial/electron-versioning.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index 0d7d86c0b1ba..5ea77d631121 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -50,11 +50,11 @@ Here are the general rules that apply when releasing new versions: |---|--- | Chromium version update | Major | Node *major* version update | Major -| Node *minor* version update | Minor | Electron breaking API change | Major +| Any other changes deemed "risky" | Major +| Node *minor* version update | Minor | Electron non-breaking API change | Minor | Electron bug fix | Patch -| Anything sufficiently "risky"\* | Major When you install an npm module with the `--save` or `--save-dev` flags, it will be prefixed with a caret `^` in package.json: From 7062a6e55d4d7c964fda19fc9b4d08a601cffcce Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 6 Oct 2017 11:47:28 -0400 Subject: [PATCH 11/12] remove the condition where release draft has to have a `prerelease` flag --- script/prerelease.js | 1 - 1 file changed, 1 deletion(-) diff --git a/script/prerelease.js b/script/prerelease.js index 20f2a108fc35..5dd4be1ff553 100755 --- a/script/prerelease.js +++ b/script/prerelease.js @@ -24,7 +24,6 @@ github.repos.getReleases({owner: 'electron', repo: 'electron'}) const draft = drafts[0] check(draft.tag_name === `v${pkg.version}`, `draft release version matches local package.json (v${pkg.version})`) - check(draft.prerelease, 'draft is a prerelease') check(draft.body.length > 50 && !draft.body.includes('(placeholder)'), 'draft has release notes') const requiredAssets = assetsForVersion(draft.tag_name).sort() From 31eb83223b62aab1b81f2cf9fbfceb009c6615c5 Mon Sep 17 00:00:00 2001 From: Vanessa Yuen Date: Fri, 6 Oct 2017 11:48:09 -0400 Subject: [PATCH 12/12] Update the documentation on the release process to reflect the new versioning policy. --- docs/development/releasing.md | 107 ++++++++++++++-------------------- 1 file changed, 45 insertions(+), 62 deletions(-) diff --git a/docs/development/releasing.md b/docs/development/releasing.md index ac3ad5a86d9a..aafee3291a48 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -2,25 +2,15 @@ This document describes the process for releasing a new version of Electron. -## Create a backport branch - -If you're about release a new major or minor version of Electron like `1.8.0`, -`1.9.0`, or `2.0.0`, first create a branch from the most recent minor release -for later backports: - -Assuming you're about to publish `1.8.0`, and the highest `1.7` release was -`1.7.6`: - -```sh -git checkout -b 1-7-x v1.7.6 -git push origin HEAD -``` +## Find out what version change is needed +Is this a major, minor, patch, or beta version change? Read the [Version Change Rules](docs/tutorial/electron-versioning.md#version-change-rules) to find out. ## Create a temporary branch -Create a new branch from `master`. Name it `release` or anything you like. +- **If releasing beta,** create a new branch from `master`. +- **If releasing a stable version,** create a new branch from the beta branch you're stablizing. -Note: If you are creating a backport release, you'll check out `1-6-x`, `1-7-x`, etc instead of `master`. +Name the new branch `release` or anything you like. ```sh git checkout master @@ -54,8 +44,6 @@ git push origin HEAD This will bump the version number in several files. See [this bump commit] for an example. -Most releases will be `patch` level. Upgrades to Chrome or other major changes should use `minor`. For more info, see [electron-versioning]. - ## Wait for builds :hourglass_flowing_sand: The presence of the word [`Bump`](https://github.com/electron/electron/blob/7961a97d7ddbed657c6c867cc8426e02c236c077/script/cibuild-linux#L3-L6) in the commit message created by the `bump-version` script @@ -73,7 +61,6 @@ Writing release notes is a good way to keep yourself busy while the builds are r For prior art, see existing releases on [the releases page]. Tips: - - Each listed item should reference a PR on electron/electron, not an issue, nor a PR from another repo like libcc. - No need to use link markup when referencing PRs. Strings like `#123` will automatically be converted to links on github.com. - To see the version of Chromium, V8, and Node in every version of Electron, visit [atom.io/download/electron/index.json](https://atom.io/download/electron/index.json). @@ -98,6 +85,16 @@ For a `patch` release, use the following format: ### Windows * Fixed a Windows thing. #1234 +``` + +### Minor releases + +For a `minor` release, e.g. `1.8.0`, use this format: + +``` +## Upgrades + +- Upgraded from Node `oldVersion` to `newVersion`. #123 ## API Changes @@ -116,33 +113,50 @@ For a `patch` release, use the following format: * Changed a Windows thing. #123 ``` -### Minor releases - -For a `minor` release (which is normally a Chromium update, and possibly also a Node update), e.g. `1.8.0`, use this format: - +### Major releases ``` -**Note:** This is a beta release. This is the first release running on upgraded versions of Chrome/Node.js/V8 and most likely will have have some instability and/or regressions. - -Please file new issues for any bugs you find in it. - -This release is published to [npm](https://www.npmjs.com/package/electron) under the `beta` tag and can be installed via `npm install electron@beta`. - ## Upgrades -- Upgraded from Chrome `oldVersion` to `newVersion`. #123 +- Upgraded from Chromium `oldVersion` to `newVersion`. #123 - Upgraded from Node `oldVersion` to `newVersion`. #123 -- Upgraded from v8 `oldVersion` to `newVersion`. #9116 + +## Breaking API changes + +* Changed a thing. #123 + +### Linux + +* Changed a Linux thing. #123 + +### macOS + +* Changed a macOS thing. #123 + +### Windows + +* Changed a Windows thing. #123 ## Other Changes - Some other change. #123 ``` +### Beta releases +Use the same formats as the ones suggested above, but add the following note at the beginning of the changelog: +``` +**Note:** This is a beta release and most likely will have have some instability and/or regressions. + +Please file new issues for any bugs you find in it. + +This release is published to [npm](https://www.npmjs.com/package/electron) under the `beta` tag and can be installed via `npm install electron@beta`. +``` + + ## Edit the release draft 1. Visit [the releases page] and you'll see a new draft release with placeholder release notes. 1. Edit the release and add release notes. -1. Ensure the `prerelease` checkbox is checked. This should happen automatically for Electron versions >=1.7 +1. Uncheck the `prerelease` checkbox if you're publishing a stable release; leave it checked for beta releases. 1. Click 'Save draft'. **Do not click 'Publish release'!** 1. Wait for all builds to pass before proceeding. @@ -209,37 +223,6 @@ git push origin :release # delete remote branch [this bump commit]: https://github.com/electron/electron/commit/78ec1b8f89b3886b856377a1756a51617bc33f5a [electron-versioning]: /docs/tutorial/electron-versioning.md -## Promote a release on npm - -New releases are published to npm with the `beta` tag. Every release should -eventually get promoted to stable unless there's a good reason not to. - -Releases are normally given around two weeks in the wild before being promoted. -Before promoting a release, check to see if there are any bug reports -against that version, e.g. issues labeled with `version/1.7.x`. - -It's also good to ask users in Slack if they're using the beta versions successfully. - -To see what's beta and stable at any given time: - -``` -$ npm dist-tag ls electron -beta: 1.7.5 -latest: 1.6.11 -``` - -To promote a beta version to stable (aka `latest`): - -``` -npm dist-tag add electron@1.2.3 latest -``` - -Then edit the release on GitGub: - -1. Remove `beta` from the release name: electron v1.7.5 ~~beta~~ -1. Uncheck the `prerelease` checkbox. -1. Click "Update release" - ## Fix missing binaries of a release manually In the case of a corrupted release with broken CI machines, we might have to