Releasing

This document describes the process for releasing a new version of Electron.

Determine which branch to release from

• If releasing beta, run the scripts below from master.
• If releasing a stable version, run the scripts below from the branch you're stabilizing.

Find out what version change is needed

Run npm run prepare-release -- --notesOnly to view auto generated release notes. The notes generated should help you determine if this is a major, minor, patch, or beta version change. Read the Version Change Rules for more information.

NB: If releasing from a branch, e.g. 1-8-x, check out the branch with git checkout 1-8-x rather than git checkout -b remotes/origin/1-8-x. The scripts need git rev-parse --abbrev-ref HEAD to return a short name, e.g. no remotes/origin/

Set your tokens and environment variables

You'll need Electron S3 credentials in order to create and upload an Electron release. Contact a team member for more information.

There are a handful of *_TOKEN environment variables needed by the release scripts. Once you've generated these per-user tokens, you may want to keep them in a local file that you can source when starting a release.

• ELECTRON_GITHUB_TOKEN: Create as described at https://github.com/settings/tokens/new, giving the token repo access scope.
• APPVEYOR_TOKEN: Create a token from https://windows-ci.electronjs.org/api-token If you don't have an account, ask a team member to add you.
• CIRCLE_TOKEN: Create a token from "Personal API Tokens" at https://circleci.com/account/api

Run the prepare-release script

The prepare release script will do the following: 1. Check if a release is already in process and if so it will halt. 2. Create a release branch. 3. Bump the version number in several files. See this bump commit for an example. 4. Create a draft release on GitHub with auto-generated release notes. 5. Push the release branch. 6. Call the APIs to run the release builds.

Once you have determined which type of version change is needed, run the prepare-release script with arguments according to your need:

• [major|minor|patch|beta] to increment one of the version numbers, or
• --stable to indicate this is a stable version

For example:

Major version change

npm run prepare-release -- major

Minor version change

npm run prepare-release -- minor

Patch version change

npm run prepare-release -- patch

Beta version change

npm run prepare-release -- beta

Promote beta to stable

npm run prepare-release -- --stable

Tip: You can test the new version number before running prepare-release with a dry run of the bump-version script with the same major/minor/patch/beta arguments, e.g.:

$ ./script/bump-version.py --bump minor --dry-run

Wait for builds ⏳

The prepare-release script will trigger the builds via API calls. To monitor the build progress, see the following pages:

• circleci.com/gh/electron/electron for OS X and Linux
• windows-ci.electronjs.org/project/AppVeyor/electron for Windows

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.

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

Minor releases

For a minor release, e.g. 1.8.0, use this format:

## Upgrades
  
  - Upgraded from Node `oldVersion` to `newVersion`. #123
  
  ## API Changes
  
  * Changed a thing. #123
  
  ### Linux
  
  * Changed a Linux thing. #123
  
  ### macOS
  
  * Changed a macOS thing. #123
  
  ### Windows
  
  * Changed a Windows thing. #123

Major releases

## Upgrades
  
  - Upgraded from Chromium `oldVersion` to `newVersion`. #123
  - Upgraded from Node `oldVersion` to `newVersion`. #123
  
  ## 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.
2. Edit the release and add release notes.
3. Uncheck the prerelease checkbox if you're publishing a stable release; leave it checked for beta releases.
4. Click 'Save draft'. Do not click 'Publish release'!
5. Wait for all builds to pass before proceeding.
6. In the release branch, verify that the release's files have been created:

$ git rev-parse --abbrev-ref HEAD
  release
  $ npm run release -- --validateRelease

Merge temporary branch (pre-2-0-x branches only)

Once the release builds have finished, merge the release branch back into the source release branch using the merge-release script. If the branch cannot be successfully merged back this script will automatically rebase the release branch and push the changes which will trigger the release builds again, which means you will need to wait for the release builds to run again before proceeding.

Merging back into master

npm run merge-release -- master

Merging back into old release branch

npm run merge-release -- 1-7-x

Publish the release

Once the merge has finished successfully, run the release script via npm run release to finish the release process. This script will do the following: 1. Build the project to validate that the correct version number is being released. 2. Download the binaries and generate the node headers and the .lib linker used on Windows by node-gyp to build native modules. 3. Create and upload the SHASUMS files stored on S3 for the node files. 4. Create and upload the SHASUMS256.txt file stored on the GitHub release. 5. Validate that all of the required files are present on GitHub and S3 and have the correct checksums as specified in the SHASUMS files. 6. Publish the release on GitHub 7. Delete the release branch.

Publish to npm

Before publishing to npm, you'll need to log into npm as Electron. Optionally, you may find npmrc to be a useful way to keep Electron's profile side-by-side with your own:

$ sudo npm install -g npmrc
  $ npmrc -c electron
  Removing old .npmrc (default)
  Activating .npmrc "electron"

The Electron account's credentials are kept by GitHub. "Electron - NPM" for the URL "https://www.npmjs.com/login".

$ npm login
  Username: electron
  Password:
  Email: (this IS public) [email protected]

Publish the release to npm.

$ npm whoami
  electron
  $ npm run publish-to-npm

Note: In general you should be using the latest Node during this process; however, older versions of the publish-to-npm script may have trouble with Node 7 or higher. If you have trouble with this in an older branch, try running with an older version of Node, e.g. a 6.x LTS.

Fix missing binaries of a release manually

In the case of a corrupted release with broken CI machines, we might have to re-upload the binaries for an already published release.

The first step is to go to the Releases page and delete the corrupted binaries with the SHASUMS256.txt checksum file.

Then manually create distributions for each platform and upload them:

# Checkout the version to re-upload.
  git checkout vTHE.RELEASE.VERSION
  
  # Do release build, specifying one target architecture.
  ./script/bootstrap.py --target_arch [arm|x64|ia32]
  ./script/build.py -c R
  ./script/create-dist.py
  
  # Explicitly allow overwritting a published release.
  ./script/upload.py --overwrite

After re-uploading all distributions, publish again to upload the checksum file:

npm run release