Doc - Release using channels

docs/SUMMARY.md

@@ -26,8 +26,9 @@
   * [Loading App Dependencies Manually](tutorials/loading-app-dependencies-manually.md)
   * [Two package.json Structure](tutorials/two-package-structure.md)
   * [macOS Kernel Extensions](tutorials/macos-kernel-extensions.md)
+  * [Release Using Channels](tutorials/release-using-channels.md)
 
 * Programmatic API
   * [electron-builder](api/electron-builder.md)
 
-* [Donate](donate.md)
+* [Donate](donate.md)

docs/auto-update.md

@@ -130,6 +130,7 @@ Emitted on progress.
         * [`.downloadUpdate(cancellationToken)`](#module_electron-updater.AppUpdater+downloadUpdate) ⇒ <code>Promise&lt;any&gt;</code>
         * [`.getFeedURL()`](#module_electron-updater.AppUpdater+getFeedURL) ⇒ <code>undefined</code> \| <code>null</code> \| <code>String</code>
         * [`.setFeedURL(options)`](#module_electron-updater.AppUpdater+setFeedURL)
+        * [`.channel()`](#module_electron-updater.AppUpdater+channel)
         * [`.quitAndInstall(isSilent, isForceRunAfter)`](#module_electron-updater.AppUpdater+quitAndInstall)
     * [`.Logger`](#Logger)
         * [`.debug(message)`](#module_electron-updater.Logger+debug)
@@ -168,6 +169,7 @@ Emitted on progress.
     * [`.downloadUpdate(cancellationToken)`](#module_electron-updater.AppUpdater+downloadUpdate) ⇒ <code>Promise&lt;any&gt;</code>
     * [`.getFeedURL()`](#module_electron-updater.AppUpdater+getFeedURL) ⇒ <code>undefined</code> \| <code>null</code> \| <code>String</code>
     * [`.setFeedURL(options)`](#module_electron-updater.AppUpdater+setFeedURL)
+    * [`.channel()`](#module_electron-updater.AppUpdater+channel)
     * [`.quitAndInstall(isSilent, isForceRunAfter)`](#module_electron-updater.AppUpdater+quitAndInstall)
 
 <a name="module_electron-updater.AppUpdater+checkForUpdates"></a>
@@ -193,6 +195,10 @@ Configure update provider. If value is `string`, [GenericServerOptions](/configu
 
 - options <code>[PublishConfiguration](/configuration/publish.md#publishconfiguration)</code> | <code>String</code> | <code>[GithubOptions](/configuration/publish.md#githuboptions)</code> | <code>[S3Options](/configuration/publish.md#s3options)</code> | <code>[SpacesOptions](/configuration/publish.md#spacesoptions)</code> | <code>[GenericServerOptions](/configuration/publish.md#genericserveroptions)</code> | <code>[BintrayOptions](/configuration/publish.md#bintrayoptions)</code> - If you want to override configuration in the `app-update.yml`.
 
+<a name="module_electron-updater.AppUpdater+channel"></a>
+#### `appUpdater.channel` (getter and setter)
+Define the channel which the Auto-Updater will follow (see [the auto-update with channels tutorial](tutorials/release-using-channels.md#release_using_channels)) using `appUpdater.channel = 'beta'` or get the current channel with `currentChannel = appUpdater.channel`.
+
 <a name="module_electron-updater.AppUpdater+quitAndInstall"></a>
 #### `appUpdater.quitAndInstall(isSilent, isForceRunAfter)`
 Restarts the app and installs the update after it has been downloaded.

docs/tutorials/release-using-channels.md

@@ -0,0 +1,53 @@
+<a name="release_using_channels"></a>
+# Release Using Channels / Auto-Updates With Channels
+
+## Description
+Channels are useful to distribute "beta" or "alpha" releases of your application to a chosen set of users. This allows to test an application before release it as "latest" (stable).
+
+Users which receive "beta" version will get "latest" versions too. Otherwise, users who don't want "beta" will only get "latest" releases.
+
+There are three channels, ordered by stability:
+1. "latest", your application is stable and this is the default one (example: "1.3.2")
+2. "beta" which means your application works, but should have some bugs (example: "1.3.2-beta")
+3. "alpha" which means your application is not stable and in active development (example: "1.3.2-alpha")
+
+
+## Configuration
+To release using channels, you should config electron-builder and define the channels to use in client side.
+
+### Electron-Builder
+By default (without using channels), all application releases use the "latest" channel.
+
+If you want to use channels, you should add this to your package.json:
+
+```
+"version": "x.x.x-beta",
+...
+"build": {
+  "generateUpdatesFilesForAllChannels": true,
+  ...
+}
+```
+
+> Note: `allowDowngrade` is automatically set to `true` when `generateUpdatesFilesForAllChannels = true`, so you don't need to set it.
+
+All you have to do to release using channels is to define the channel in the version tag of the `package.json`. Add "-beta" or "-alpha" (nothing for "latest") to automatically build for the related channel.
+
+
+### Your Application
+All you need to do here is to define which channel the user will receive with:
+
+`autoUpdater.channel = 'beta'` (see [the documentation here](../auto-update.md#module_electron-updater.AppUpdater+channel))
+
+The following versions will be distributed to users depending on the channel defined:
+- "latest" or nothing: users will only get "latest" versions
+- "beta": users will get "beta" and "latest" version
+- "alpha": users will get "alpha", "beta" and "latest" version
+
+
+## How To Use It / Example
+Imagine that your application is stable and in version 1.0.1.
+
+If you want to release a beta for the new 1.1.0 version, you only need to update the package.json "version" with "1.1.0-beta".
+
+When your application is stable enough, you want to release it to all users. For that, you only need to remove the "-beta" label from the package.json "version" tag.