Merge pull request #10251 from electron/new-update-docs

New guide for implementing updates

docs/README.md

@@ -33,6 +33,7 @@ an issue:
 * [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
 * [Offscreen Rendering](tutorial/offscreen-rendering.md)
 * [Keyboard Shortcuts](tutorial/keyboard-shortcuts.md)
+* [Updating Applications](tutorial/updates.md)
 
 ## Tutorials
 

docs/api/auto-updater.md

@@ -4,24 +4,15 @@
 
 Process: [Main](../glossary.md#main-process)
 
-The `autoUpdater` module provides an interface for the
-[Squirrel](https://github.com/Squirrel) framework.
+**You can find a detailed guide about how to implement updates into your application [here](../tutorial/updates.md).**
 
-You can quickly launch a multi-platform release server for distributing your
-application by using one of these projects:
+## Platform Notices
 
-- [nuts][nuts]: *A smart release server for your applications, using GitHub as a backend. Auto-updates with Squirrel (Mac & Windows)*
-- [electron-release-server][electron-release-server]: *A fully featured,
-  self-hosted release server for electron applications, compatible with
-  auto-updater*
-- [squirrel-updates-server][squirrel-updates-server]: *A simple node.js server
-  for Squirrel.Mac and Squirrel.Windows which uses GitHub releases*
-- [squirrel-release-server][squirrel-release-server]: *A simple PHP application for Squirrel.Windows which reads updates from a folder. Supports delta updates.*
+Currently, only macOS and Windows are supported. There is no built-in support
+for auto-updater on Linux, so it is recommended to use the
+distribution's package manager to update your app.
 
-## Platform notices
-
-Though `autoUpdater` provides a uniform API for different platforms, there are
-still some subtle differences on each platform.
+In addition, there are some subtle differences on each platform:
 
 ### macOS
 
@@ -54,11 +45,6 @@ Unlike Squirrel.Mac, Windows can host updates on S3 or any other static file hos
 You can read the documents of [Squirrel.Windows][squirrel-windows] to get more details
 about how Squirrel.Windows works.
 
-### Linux
-
-There is no built-in support for auto-updater on Linux, so it is recommended to
-use the distribution's package manager to update your app.
-
 ## Events
 
 The `autoUpdater` object emits the following events:
@@ -134,7 +120,3 @@ from the normal quit event sequence.
 [installer-lib]: https://github.com/electron/windows-installer
 [electron-forge-lib]: https://github.com/electron-userland/electron-forge
 [app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx
-[electron-release-server]: https://github.com/ArekSredzki/electron-release-server
-[squirrel-updates-server]: https://github.com/Aluxian/squirrel-updates-server
-[nuts]: https://github.com/GitbookIO/nuts
-[squirrel-release-server]: https://github.com/Arcath/squirrel-release-server

docs/tutorial/updates.md

@@ -0,0 +1,96 @@
+# Updating Applications
+
+There are several ways to update an Electron application. The easiest and 
+officially supported one is taking advantage of the built-in 
+[Squirrel](https://github.com/Squirrel) framework and 
+Electron's [autoUpdater](../api/auto-updater.md) module.
+
+## Deploying an update server
+
+To get started, you first need to deploy a server that the 
+[autoUpdater](../api/auto-updater.md) module will download new updates from.
+
+Depending on your needs, you can choose from one of these:
+
+- [Hazel](https://github.com/zeit/hazel) – Simple update server for open-source 
+apps. Pulls from 
+[GitHub Releases](https://help.github.com/articles/creating-releases/) 
+and can be deployed for free on [Now](https://zeit.co/now).
+- [Nuts](https://github.com/GitbookIO/nuts) – Also uses 
+[GitHub Releases](https://help.github.com/articles/creating-releases/), 
+but caches app updates on disk and supports private repositories.
+- [electron-release-server](https://github.com/ArekSredzki/electron-release-server) – 
+Provides a dashboard for handling releases
+
+## Implementing updates in your app
+
+Once you've deployed your update server, continue with importing the required 
+modules in your code. The following code might vary for different server 
+software, but it works like described when using 
+[Hazel](https://github.com/zeit/hazel).
+
+**Important:** Please ensure that the code below will only be executed in 
+your packaged app, and not in development. You can use 
+[electron-is-dev](https://github.com/sindresorhus/electron-is-dev) to check for 
+the environment.
+
+```js
+const {app, autoUpdater, dialog} = require('electron')
+```
+
+Next, construct the URL of the update server and tell 
+[autoUpdater](../api/auto-updater.md) about it:
+
+```js
+const server = 'https://your-deployment-url.com'
+const feed = `${server}/update/${process.platform}/${app.getVersion()}`
+
+autoUpdater.setFeedURL(feed)
+```
+
+As the final step, check for updates. The example below will check every minute:
+
+```js
+setInterval(() => {
+  autoUpdater.checkForUpdates()
+}, 60000)
+```
+
+Once your application is [packaged](../tutorial/application-distribution.md), 
+it  will receive an update for each new 
+[GitHub Release](https://help.github.com/articles/creating-releases/) that you 
+publish.
+
+## Applying updates
+
+Now that you've configured the basic update mechanism for your application, you 
+need to ensure that the user will get notified when there's an update. This
+can be achieved using the autoUpdater API 
+[events](../api/auto-updater.md#events):
+
+```js
+autoUpdater.on('update-downloaded', (event, releaseNotes, releaseName) => {
+  const dialogOpts = {
+    type: 'info',
+    buttons: ['Restart', 'Later'],
+    title: 'Application Update',
+    message: process.platform === 'win32' ? releaseNotes : releaseName,
+    detail: 'A new version has been downloaded. Restart the application to apply the updates.'
+  }
+
+  dialog.showMessageBox(dialogOpts, (response) => {
+    if (response === 0) autoUpdater.quitAndInstall()
+  })
+})
+```
+
+Also make sure that errors are 
+[being handled](../api/auto-updater.md#event-error). Here's an example
+for logging them to `stderr`:
+
+```js
+autoUpdater.on('error', message => {
+  console.error('There was a problem updating the application')
+  console.error(message)
+})
+```