mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Merge pull request #10336 from electron/document-prereleases

Browse source 
document new release and versioning process
This commit is contained in:
Zeke Sikelianos 2017-10-06 22:14:42 -07:00 committed by GitHub
commit 61e606bedc
5 changed files with 233 additions and 90 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

107
docs/development/releasing.md
View file

@ -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

97
docs/images/tutorial-release-schedule.svg Normal file
View file

@ -0,0 +1,97 @@
<?xml version="1.0" standalone="yes"?>
<svg width="520" height="220" version="1.1" xmlns="http://www.w3.org/2000/svg">
<marker id="arrow" viewBox="-1 0 12 10" refX="10.5" refY="5" markerWidth="8" markerHeight="8" orient="auto">
<path d="M 0 0 L 10 5 L 0 10"/>
</marker>
<g transform="translate(0,40)">
<!-- master -->
<text x="60" y="30" text-anchor="end" alignment-baseline="middle">master</text>
<path d="M70 30 H 500" stroke-width="2" stroke="black"/>
<!-- v2.0 -->
<g>
<path d="M100 30 l 20 30 H 200" stroke-width="2" stroke="black" fill="transparent"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle">2.0</text>
<circle cx="120" cy="60" r="5"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 120,60)">v2.0.0-beta0</text>
<circle cx="200" cy="60" r="5"/>
<text x="190" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 200,60)">v2.0.0</text>
</g>
<!-- v2.1 -->
<g transform="translate(130,0)">
<path d="M100 30 l 20 30 H 200" stroke-width="2" stroke="black" fill="transparent"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle">2.1</text>
<circle cx="120" cy="60" r="5"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 120,60)">v2.1.0-beta0</text>
<circle cx="160" cy="60" r="5"/>
<text x="150" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 160,60)">v2.1.0-beta1</text>
<circle cx="200" cy="60" r="5"/>
<text x="190" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 200,60)">v2.1.0</text>
</g>
<!-- v3.0 -->
<g transform="translate(260,0)">
<path d="M100 30 l 20 30 H 200" stroke-width="2" stroke="black" fill="transparent"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle">3.0</text>
<circle cx="120" cy="60" r="5"/>
<text x="110" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 120,60)">v3.0.0-beta0</text>
<circle cx="200" cy="60" r="5"/>
<text x="190" y="60" text-anchor="end" alignment-baseline="middle" transform="rotate(-60 200,60)">v3.0.0</text>
</g>
<!-- Bug fixes -->
<g transform="translate(160,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">bug fix</text>
<path d="M0 0 l0,30" marker-end="url(#arrow)" stroke-dasharray="2,2" stroke="#000"/>
</g>
<g transform="translate(260,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">bug fix</text>
<path d="M0 0 l0,30" marker-end="url(#arrow)" stroke-dasharray="2,2" stroke="#000"/>
</g>
<g transform="translate(280,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">bug fix</text>
<path d="M0 0 l0,30" marker-end="url(#arrow)" stroke-dasharray="2,2" stroke="#000"/>
</g>
<g transform="translate(400,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">bug fix</text>
<path d="M0 0 l0,30" marker-end="url(#arrow)" stroke-dasharray="2,2" stroke="#000"/>
</g>
<g transform="translate(430,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">bug fix</text>
<path d="M0 0 l0,30" marker-end="url(#arrow)" stroke-dasharray="2,2" stroke="#000"/>
</g>
<!-- Features -->
<g transform="translate(130,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">feature</text>
</g>
<g transform="translate(200,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">feature</text>
</g>
<g transform="translate(340,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)">feature</text>
</g>
<!-- Chromium update -->
<g transform="translate(310,30)">
<circle cx="0" cy="0" r="3"/>
<text x="10" y="0" text-anchor="start" alignment-baseline="middle" transform="rotate(-60 0,0)"><tspan>chromium</tspan><tspan dy="10" x="10">update</tspan></text>
</g>
<!-- Timeline -->
<g transform="translate(100,160)">
<text x="50" y="0" text-anchor="middle" alignment-baseline="text-after-edge">~1 week</text>
<path d="M0 0 l0 10 l0 -5 H100l0 -5l0 10" stroke-width="2" stroke="black" fill="transparent"/>
</g>
<g transform="translate(230,160)">
<text x="50" y="0" text-anchor="middle" alignment-baseline="text-after-edge">~1 week</text>
<path d="M0 0 l0 10 l0 -5 H100l0 -5l0 10" stroke-width="2" stroke="black" fill="transparent"/>
</g>
<g transform="translate(360,160)">
<text x="50" y="0" text-anchor="middle" alignment-baseline="text-after-edge">~1 week</text>
<path d="M0 0 l0 10 l0 -5 H100l0 -5l0 10" stroke-width="2" stroke="black" fill="transparent"/>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 5.3 KiB

111
docs/tutorial/electron-versioning.md
View file

@ -1,9 +1,9 @@
# Electron 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.
## 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.
Semantic versions are always made up of three numbers:
```
@ -22,34 +22,99 @@ A simple mnemonic for remembering this scheme is as follows:
breaking.feature.fix
```
## Electron Versioning
## Before Version 2
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
reference a specific version of Electron.**
Before version 2 of Electron we didn't follow SemVer, instead the following was used:
Electron version numbers are bumped using the following rules:
- **Major**: Breaking changes to Electron's API
- **Minor**: Major Chrome, minor node or "significant" Electron changes
- **Patch**: New features and bug fixes
* **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
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.
This system had a number of drawbacks, such as:
We recommend that you set a fixed version when installing Electron from npm:
- 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
```sh
npm install electron --save-exact --save-dev
## Version 2 and Beyond
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
Here are the general rules that apply when releasing new versions:
| Type of change | Version increase
|---|---
| Chromium version update | Major
| Node *major* version update | Major
| 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
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 `--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 [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, 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.
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.
### The Release Schedule
**Note: The schedule outlined here is _aspirational_. We are not yet cutting
releases at a weekly cadence, but we hope to get there eventually.**
<img style="width:100%;margin:20px 0;" src="../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 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:
```
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

7
docs/tutorial/installation.md
View file

@ -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

1
script/prerelease.js
View file

@ -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()