add code signing tutorial (#12767)

* docs: add code signing tutorial

* docs: link to code signing tutorial from readme

* docs: remove unneeded use of "application" from docs readme

docs/README.md

@@ -50,27 +50,29 @@ an issue:
   * [Offline/Online Detection](tutorial/online-offline-events.md)
   * [Represented File for macOS BrowserWindows](tutorial/represented-file.md)
   * [Native File Drag & Drop](tutorial/native-file-drag-drop.md)
-* [Application Accessibility](tutorial/accessibility.md)
+* [Accessibility](tutorial/accessibility.md)
   * [Spectron](tutorial/accessibility.md#spectron)
   * [Devtron](tutorial/accessibility.md#devtron)
   * [Enabling Accessibility](tutorial/accessibility.md#enabling-accessibility)
-* [Application Testing and Debugging](tutorial/application-debugging.md)
+* [Testing and Debugging](tutorial/application-debugging.md)
   * [Debugging the Main Process](tutorial/debugging-main-process.md)
   * [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
   * [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
   * [DevTools Extension](tutorial/devtools-extension.md)
   * [Automated Testing with a Custom Driver](tutorial/automated-testing-with-a-custom-driver.md)
-* [Application Distribution](tutorial/application-distribution.md)
+* Packaging
+  * [Code Signing](tutorial/code-signing.md)
+* [Distribution](tutorial/application-distribution.md)
   * [Support](tutorial/support.md)
   * [Mac App Store](tutorial/mac-app-store-submission-guide.md)
   * [Windows Store](tutorial/windows-store-guide.md)
   * [Snapcraft](tutorial/snapcraft.md)
-* [Application Security](tutorial/security.md)
+* [Security](tutorial/security.md)
   * [Reporting Security Issues](tutorial/security.md#reporting-security-issues)
   * [Chromium Security Issues and Upgrades](tutorial/security.md#chromium-security-issues-and-upgrades)
   * [Electron Security Warnings](tutorial/security.md#electron-security-warnings)
   * [Security Checklist](tutorial/security.md#checklist-security-recommendations)
-* [Application Updates](tutorial/updates.md)
+* [Updates](tutorial/updates.md)
   * [Deploying an Update Server](tutorial/updates.md#deploying-an-update-server)
   * [Implementing Updates in Your App](tutorial/updates.md#implementing-updates-in-your-app)
   * [Applying Updates](tutorial/updates.md#applying-updates)

docs/tutorial/code-signing.md

@@ -0,0 +1,46 @@
+# Code Signing
+
+Code signing is a security technology that you use to certify that an app was 
+created by you. Once an app is signed, the system can detect any change to the 
+app, whether the change is introduced accidentally or by malicious code.
+
+While it is possible to distribute unsigned apps, it is not recommended. 
+For example, here's what macOS users see when attempting to start an unsigned app:
+
+![unsigned app warning on macOS](https://user-images.githubusercontent.com/2289/39488937-bdc854ba-4d38-11e8-88f8-7b3c125baefc.png)
+
+> App can't be opened because it is from an unidentified developer
+
+If you are building an Electron app that you intend to package and distribute, 
+it should be code signed. The Mac and Windows app stores do not allow unsigned 
+apps.
+
+# Signing macOS builds
+
+Before signing macOS builds, you must do the following:
+
+1. Enroll in the [Apple Developer Program](Apple Developer Program) (requires an annual fee)
+2. Download and install Xcode
+3. Generate, download, and install [signing certificates]
+
+There are a number of tools for signing your packaged app:
+
+- [`electron-osx-sign`] is a standalone tool for signing macOS packages.
+- [`electron-packager`] bundles `electron-osx-sign`. If you're using `electron-packager`,
+pass the `--osx-sign=true` flag to sign your build.
+- [`electron-builder`] has built-in code-signing capabilities. See [electron.build/code-signing](https://www.electron.build/code-signing)
+
+For more info, see the [Mac App Store Submission Guide].
+
+# Signing Windows builds
+
+See the [Windows Store Guide].
+
+[Apple Developer Program]: https://developer.apple.com/programs/
+[`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign
+[`electron-packager`]: https://github.com/electron-userland/electron-packager
+[`electron-builder`]: https://github.com/electron/electron-builder
+[Xcode]: https://developer.apple.com/xcode
+[signing certificates]: https://github.com/electron-userland/electron-osx-sign/wiki/1.-Getting-Started#certificates
+[Mac App Store Submission Guide]: mac-app-store-submission-guide.md
+[Windows Store Guide]: windows-store-guide.md