Merge pull request #358 from Lange/clarify-docs-part-2

Clarify Documentation (Part 2)

README.md

@@ -83,8 +83,10 @@ Please note — packaged into an asar archive [by default](https://github.com/el
 * `.full-nupkg`: required for Squirrel.Windows.
 * `-amd64.deb` and `-i386.deb`: Linux Debian package. Please note — by default the most effective [xz](https://en.wikipedia.org/wiki/Xz) compression format used.
 
-You need to deploy somewhere releases/downloads server.
-Consider to use [Nuts](https://github.com/GitbookIO/nuts) (GitHub as a backend to store assets) or [Electron Release Server](https://github.com/ArekSredzki/electron-release-server).
+For auto updating to work, you must implement and configure Electron's [`autoUpdater`](http://electron.atom.io/docs/latest/api/auto-updater/) module ([example](https://github.com/develar/onshape-desktop-shell/blob/master/src/AppUpdater.ts)).
+You also need to deploy your releases to a server.
+Consider using [Nuts](https://github.com/GitbookIO/nuts) (GitHub as a backend to store assets) or [Electron Release Server](https://github.com/ArekSredzki/electron-release-server).
+See the [Publishing Artifacts](https://github.com/electron-userland/electron-builder/wiki/Publishing-Artifacts) section of the [Wiki](https://github.com/electron-userland/electron-builder/wiki) for information on configuring your CI environment for automatic deployment.
 
 # Build Version Management
 `CFBundleVersion` (OS X) and `FileVersion` (Windows) will be set automatically to `version`.`build_number` on CI server (Travis, AppVeyor and CircleCI supported).
@@ -99,3 +101,6 @@ See `node_modules/electron-builder/out/electron-builder.d.ts`. [Typings](https:/
 
 [npm-url]: https://npmjs.org/package/electron-builder
 [npm-image]: http://img.shields.io/npm/v/electron-builder.svg
+
+# Further Reading
+See the [Wiki](https://github.com/electron-userland/electron-builder/wiki) for more documentation.

docs/Options.md

@@ -69,7 +69,7 @@ See all [appdmg options](https://www.npmjs.com/package/appdmg#json-specification
 | Name | Description
 | --- | ---
 | icon | <a name="OsXBuildOptions-icon"></a>The path to icon, which will be shown when mounted (default: `build/icon.icns`).
-| background | <a name="OsXBuildOptions-background"></a>The path to background (default: `build/background.png`).
+| background | <a name="OsXBuildOptions-background"></a>The path to background (default: `build/background.png`). The resolution of this file determines the resolution of the installer window.
 | target | <a name="OsXBuildOptions-target"></a>Target package type: list of `default`, `dmg`, `zip`, `mas`.
 
 <a name="WinBuildOptions"></a>

docs/Publishing Artifacts.md

@@ -13,20 +13,27 @@ Currently, only GitHub Releases is supported.
 | `always`       | always publish
 | `never`        | never publish
 
-But please consider to use automatic rules and don't specify `publish` explicitly:
+But please consider using automatic rules instead of explicitly specifying `publish`:
 
 * If CI server detected, — `onTagOrDraft`.
 
- What does it means? [Draft a new release](https://help.github.com/articles/creating-releases/) (version (`v1.0`) must be equals to version (`1.0`) in the application `package.json`) and each CI build will update artifacts. It allows you to get latest artifacts in any time and publish release once it is ready.
+ > **NOTICE**: _This is the recommended workflow._
+
+ 1. [Draft a new release](https://help.github.com/articles/creating-releases/). Set the "Tag version" to the value of `version` in your application `package.json`, and prefix it with `v`. "Release title" can be anything you want.
+   - For example, if your application `package.json` version is `1.0`, your draft's "Tag version" would be `v1.0`.
+ 2. Push some commits. Every CI build will update the artifacts attached to this draft.
+ 3. Once you are done, publish the release. GitHub will tag the latest commit for you.
+
+ The benefit of this workflow is that it allows you to always have the latest artifacts, and the release can be published once it is ready.
 
 * If CI server reports that tag was pushed, — `onTag`.
 
- Release will be drafted (if doesn't exists) and artifacts published only and only if tag was pushed.
+ Release will be drafted (if doesn't already exist) and artifacts published only if tag was pushed.
 
 * If [npm script](https://docs.npmjs.com/misc/scripts) named `release`, — `always`.
 
  Add to `scripts` in the development `package.json`:
  ```json
-"release": "build"
-```
- and if you run `npm run release`, release will be drafted (if doesn't exists) and artifacts published.
+ "release": "build"
+ ```
+ and if you run `npm run release`, a release will be drafted (if doesn't already exist) and artifacts published.

src/metadata.ts

@@ -155,7 +155,7 @@ export interface OsXBuildOptions extends PlatformSpecificBuildOptions {
   readonly icon?: string
 
   /*
-   The path to background (default: `build/background.png`).
+   The path to background (default: `build/background.png`). The resolution of this file determines the resolution of the installer window.
    */
   readonly background?: string