diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 1cc3f771ead..98faaded96d 100644 --- a/docs/SUMMARY.md +++ b/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) \ No newline at end of file +* [Donate](donate.md) diff --git a/docs/auto-update.md b/docs/auto-update.md index ee09486448b..44d5a518558 100644 --- a/docs/auto-update.md +++ b/docs/auto-update.md @@ -130,6 +130,7 @@ Emitted on progress. * [`.downloadUpdate(cancellationToken)`](#module_electron-updater.AppUpdater+downloadUpdate) ⇒ Promise<any> * [`.getFeedURL()`](#module_electron-updater.AppUpdater+getFeedURL) ⇒ undefined \| null \| String * [`.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) ⇒ Promise<any> * [`.getFeedURL()`](#module_electron-updater.AppUpdater+getFeedURL) ⇒ undefined \| null \| String * [`.setFeedURL(options)`](#module_electron-updater.AppUpdater+setFeedURL) + * [`.channel()`](#module_electron-updater.AppUpdater+channel) * [`.quitAndInstall(isSilent, isForceRunAfter)`](#module_electron-updater.AppUpdater+quitAndInstall) @@ -193,6 +195,10 @@ Configure update provider. If value is `string`, [GenericServerOptions](/configu - options [PublishConfiguration](/configuration/publish.md#publishconfiguration) | String | [GithubOptions](/configuration/publish.md#githuboptions) | [S3Options](/configuration/publish.md#s3options) | [SpacesOptions](/configuration/publish.md#spacesoptions) | [GenericServerOptions](/configuration/publish.md#genericserveroptions) | [BintrayOptions](/configuration/publish.md#bintrayoptions) - If you want to override configuration in the `app-update.yml`. + +#### `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`. + #### `appUpdater.quitAndInstall(isSilent, isForceRunAfter)` Restarts the app and installs the update after it has been downloaded. diff --git a/docs/tutorials/release-using-channels.md b/docs/tutorials/release-using-channels.md new file mode 100644 index 00000000000..faf9f9c372a --- /dev/null +++ b/docs/tutorials/release-using-channels.md @@ -0,0 +1,53 @@ + +# 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.