diff --git a/docs/development/releasing.md b/docs/development/releasing.md index 111a10ea5239..3123b97c3cf1 100644 --- a/docs/development/releasing.md +++ b/docs/development/releasing.md @@ -2,13 +2,11 @@ This document describes the process for releasing a new version of Electron. -## Compile release notes - -The current process is to maintain a local file, keeping track of notable changes as pull requests are merged. For examples of how to format the notes, see previous releases on [the releases page]. - ## Create a temporary branch -Create a new branch from `master` named `release`. +Create a new branch from `master`. Name it `release` or anything you like. + +Note: If you are creating a backport release, you'll check out `1-6-x`, `1-7-x`, etc instead of `master`. ```sh git checkout master @@ -18,6 +16,12 @@ git checkout -b release This branch is created as a precaution to prevent any merged PRs from sneaking into a release between the time the temporary release branch is created and the CI builds are complete. +## Check for extant drafts + +The upload script [looks for an existing draft release](https://github.com/electron/electron/blob/7961a97d7ddbed657c6c867cc8426e02c236c077/script/upload.py#L173-L181). To prevent your new release +from clobbering an existing draft, check [the releases page] and +make sure there are no drafts. + ## Bump the version Run the `bump-version` script, passing `major`, `minor`, or `patch` as an argument: @@ -31,12 +35,94 @@ This will bump the version number in several files. See [this bump commit] for a 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 +will [trigger the release process](https://github.com/electron/electron/blob/7961a97d7ddbed657c6c867cc8426e02c236c077/script/cibuild#L82-L96). + +To monitor the build progress, see the following pages: + +- [208.52.191.140:8080/view/All/builds](http://208.52.191.140:8080/view/All/builds) for Mac and Windows +- [jenkins.githubapp.com/label/chromium/](https://jenkins.githubapp.com/label/chromium/) for Linux + +## Compile release notes + +Writing release notes is a good way to keep yourself busy while the builds are running. +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). + +### Patch releases + +For a `patch` release, use the following format: + +``` +## Bug Fixes + +* Fixed a cross-platform thing. #123 + +### Linux + +* Fixed a Linux thing. #123 + +### macOS + +* Fixed a macOS thing. #123 + +### Windows + +* Fixed a Windows thing. #1234 + +## API Changes + +* Changed a thing. #123 + +### Linux + +* Changed a Linux thing. #123 + +### macOS + +* Changed a macOS thing. #123 + +### Windows + +* 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: + +``` +**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 Node `oldVersion` to `newVersion`. #123 +- Upgraded from v8 `oldVersion` to `newVersion`. #9116 + +## Other Changes + +- Some other change. #123 +``` + ## 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. Click 'Save draft'. **Do not click 'Publish release'!** -1. Wait for all the builds to pass. :hourglass_flowing_sand: +1. Wait for all builds to pass before proceeding. ## Merge temporary branch @@ -99,3 +185,28 @@ git push origin :release # delete remote branch [the releases page]: https://github.com/electron/electron/releases [this bump commit]: https://github.com/electron/electron/commit/78ec1b8f89b3886b856377a1756a51617bc33f5a [electron-versioning]: /docs/tutorial/electron-versioning.md + +## Promoting 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 +``` \ No newline at end of file