docs: auto-updater on Windows

docs/api/auto-updater.md

@@ -1,106 +1,31 @@
 # autoUpdater
 
-**This module has only been implemented for OS X.**
+This module provides an interface for the `Squirrel` auto-updater framework.
 
-Check out [atom/grunt-electron-installer](https://github.com/atom/grunt-electron-installer)
-to build a Windows installer for your app.
+## Platform notices
 
-The `auto-updater` module is a simple wrapper around the
-[Squirrel.Mac](https://github.com/Squirrel/Squirrel.Mac) framework.
+Though `autoUpdater` provides an uniform API for different platforms, there are
+still some subtle differences on each platform.
 
-Squirrel.Mac requires that your `.app` folder is signed using the
-[codesign](https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/codesign.1.html)
-utility for updates to be installed.
+### OS X
 
-## Squirrel
+On OS X the `autoUpdater` module is built upon [Squirrel.Mac][squirrel-mac], you
+don't need any special setup to make it work. For server-side requirements, you
+can read [Server Support][server-support].
 
-Squirrel is an OS X framework focused on making application updates **as safe
-and transparent as updates to a website**.
+### Windows
 
-Instead of publishing a feed of versions from which your app must select,
-Squirrel updates to the version your server tells it to. This allows you to
-intelligently update your clients based on the request you give to Squirrel.
+On Windows you have to install your app into user's machine before you can use
+the auto-updater, it is recommended to use [grunt-electron-installer][installer]
+module to generate a Windows installer.
 
-Your request can include authentication details, custom headers or a request
-body so that your server has the context it needs in order to supply the most
-suitable update.
+The server-side setup is also different from OS X, you can read the documents of
+[Squirrel.Windows][squirrel-windows] to get more details.
 
-The update JSON Squirrel requests should be dynamically generated based on
-criteria in the request and whether an update is required. Squirrel relies
-on server-side support to determine whether an update is required. See
-[Server Support](#server-support).
+### Linux
 
-Squirrel's installer is designed to be fault tolerant and ensures that any
-updates installed are valid.
-
-## Update Requests
-
-Squirrel is indifferent to the request the client application provides for
-update checking. `Accept: application/json` is added to the request headers
-because Squirrel is responsible for parsing the response.
-
-For the requirements imposed on the responses and the body format of an update
-response, see [Server Support](#server-support).
-
-Your update request must *at least* include a version identifier so that the
-server can determine whether an update for this specific version is required. It
-may also include other identifying criteria, such as operating system version or
-username, to allow the server to deliver as fine grained an update as you
-would like.
-
-How you include the version identifier or other criteria is specific to the
-server that you are requesting updates from. A common approach is to use query
-parameters, like this:
-
-```javascript
-// In the main process
-var app = require('app');
-var autoUpdater = require('auto-updater');
-autoUpdater.setFeedUrl('http://mycompany.com/myapp/latest?version=' + app.getVersion());
-```
-
-## Server Support
-
-Your server should determine whether an update is required based on the
-[Update Request](#update-requests) your client issues.
-
-If an update is required, your server should respond with a status code of
-[200 OK](http://tools.ietf.org/html/rfc2616#section-10.2.1) and include the
-[update JSON](#update-json-format) in the body. Squirrel **will** download and
-install this update, even if the version of the update is the same as the
-currently running version. To save redundantly downloading the same version
-multiple times your server must not inform the client to update.
-
-If no update is required your server must respond with a status code of
-[204 No Content](http://tools.ietf.org/html/rfc2616#section-10.2.5). Squirrel
-will check for an update again at the interval you specify.
-
-## Update JSON Format
-
-When an update is available, Squirrel expects the following schema in response
-to the update request provided:
-
-```json
-{
-  "url": "http://mycompany.com/myapp/releases/myrelease",
-  "name": "My Release Name",
-  "notes": "Theses are some release notes innit",
-  "pub_date": "2013-09-18T12:29:53+01:00"
-}
-```
-
-The only required key is "url"; the others are optional.
-
-Squirrel will request "url" with `Accept: application/zip` and only supports
-installing ZIP updates. If future update formats are supported their MIME type
-will be added to the `Accept` header so that your server can return the
-appropriate format.
-
-`pub_date` (if present) must be formatted according to ISO 8601.
-
-## Update server implementations
-
-[Nuts](https://github.com/GitbookIO/nuts) is an open source implementation of the update server described above, it integrates beautifully with GitHub releases. Nuts manages downloads and updates, it’s compatible with `Squirrel.Mac` and `Squirrel.Windows` so you get cross-platform support out of the box.
+There is not built-in support for auto-updater on Linux, it is recommended to
+use the distribution's package manager to update your app.
 
 ## Events
 
@@ -139,6 +64,8 @@ Returns:
 
 Emitted when an update has been downloaded.
 
+On Windows only `releaseName` is available.
+
 ## Methods
 
 The `autoUpdater` object has the following methods:
@@ -159,3 +86,8 @@ using this API.
 
 Restarts the app and install the update after it has been downloaded. It should
 only be called after `update-downloaded` has been emitted.
+
+[squirrel-mac]: https://github.com/Squirrel/Squirrel.Mac
+[server-support]: https://github.com/Squirrel/Squirrel.Mac#server-support
+[squirrel-windows]: https://github.com/Squirrel/Squirrel.Windows
+[installer]: https://github.com/atom/grunt-electron-installer