document new release and versioning process

docs/tutorial/electron-versioning.md

@@ -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
+
+Before version 2 of Electron we didn't follow SemVer, instead the following was used:
+
+- **Major**: Breaking changes to Electron's API
+- **Minor**: Major Chrome, minor node or "significant" Electron changes
+- **Patch**: New features and bug fixes
 
-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.**
+This system had a number of drawbacks, such as:
 
-Electron version numbers are bumped using the following rules:
+- 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 
 
-* **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.
+## Version 2 and Beyond
 
-We recommend that you set a fixed version when installing Electron from npm:
+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.
 
-```sh
-npm install electron --save-exact --save-dev
+### 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
+| Node *minor* version update | Minor
+| Electron breaking API change | Major
+| 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:
+
+```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, 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.
 
-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.
+
+### 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

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