docs: add forge-overview.md (#35473)

* docs: move forge-specific docs to electronforge.io * docs: add reference to forge icon tutorial * docs: add references to forge-overview.md * docs: add recommended * docs: update forge-overview * docs: apply code review comments Co-authored-by: Charles Kerr <charles@charleskerr.com>
electron · Sep 21, 2022 · 4ffdd28 · 4ffdd28
1 parent 9719cea
commit 4ffdd28
Show file tree

Hide file tree

Showing 6 changed files with 51 additions and 113 deletions.
diff --git a/docs/tutorial/application-distribution.md b/docs/tutorial/application-distribution.md
@@ -11,8 +11,8 @@ can either use specialized tooling or manual approaches.
 ## With tooling
 
 There are a couple tools out there that exist to package and distribute your Electron app.
-We recommend using [Electron Forge](https://www.electronforge.io). You can check out
-its documentation directly, or refer to the [Packaging and Distribution](./tutorial-5-packaging.md)
+We recommend using [Electron Forge](./forge-overview.md). You can check out
+its [documentation](https://www.electronforge.io) directly, or refer to the [Packaging and Distribution](./tutorial-5-packaging.md)
 part of the Electron tutorial.
 
 ## Manual packaging

diff --git a/docs/tutorial/boilerplates-and-clis.md b/docs/tutorial/boilerplates-and-clis.md
@@ -26,10 +26,8 @@ beginners, using a command line tool is likely to be helpful*.
 
 ## electron-forge
 
-A "complete tool for building modern Electron applications". Electron Forge
-unifies the existing (and well maintained) build tools for Electron development
-into a cohesive package so that anyone can jump right in to Electron
-development.
+Electron Forge is a tool for packaging and publishing Electron applications. It unifies Electron's tooling ecosystem
+into a single extensible interface so that anyone can jump right into making Electron apps.
 
 Forge comes with [a ready-to-use template](https://electronforge.io/templates) using Webpack as a bundler. It includes an example typescript configuration and provides two configuration files to enable easy customization. It uses the same core modules used by the
 greater Electron community (like [`electron-packager`](https://github.com/electron/electron-packager)) –

diff --git a/docs/tutorial/code-signing.md b/docs/tutorial/code-signing.md
@@ -54,85 +54,11 @@ and notarized requires a few additions to your configuration. [Forge](https://el
 collection of the official Electron tools, using [`electron-packager`],
 [`electron-osx-sign`], and [`electron-notarize`] under the hood.
 
-Let's take a look at an example `package.json` configuration with all required fields. Not all of them are
-required: the tools will be clever enough to automatically find a suitable `identity`, for instance,
-but we recommend that you are explicit.
-
-```json title="package.json" {7}
-{
-  "name": "my-app",
-  "version": "0.0.1",
-  "config": {
-    "forge": {
-      "packagerConfig": {
-        "osxSign": {
-          "identity": "Developer ID Application: Felix Rieseberg (LT94ZKYDCJ)",
-          "hardened-runtime": true,
-          "entitlements": "entitlements.plist",
-          "entitlements-inherit": "entitlements.plist",
-          "signature-flags": "library"
-        },
-        "osxNotarize": {
-          "appleId": "felix@felix.fun",
-          "appleIdPassword": "my-apple-id-password"
-        }
-      }
-    }
-  }
-}
-```
-
-The `entitlements.plist` file referenced here needs the following macOS-specific entitlements
-to assure the Apple security mechanisms that your app is doing these things
-without meaning any harm:
-
-```xml title="entitlements.plist"
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-  <dict>
-    <key>com.apple.security.cs.allow-jit</key>
-    <true/>
-    <key>com.apple.security.cs.debugger</key>
-    <true/>
-  </dict>
-</plist>
-```
-
-Note that up until Electron 12, the `com.apple.security.cs.allow-unsigned-executable-memory` entitlement was required
-as well. However, it should not be used anymore if it can be avoided.
-
-To see all of this in action, check out Electron Fiddle's source code,
-[especially its `electron-forge` configuration
-file](https://github.com/electron/fiddle/blob/master/forge.config.js).
-
-If you plan to access the microphone or camera within your app using Electron's APIs, you'll also
-need to add the following entitlements:
-
-```xml title="entitlements.plist"
-<key>com.apple.security.device.audio-input</key>
-<true/>
-<key>com.apple.security.device.camera</key>
-<true/>
-```
-
-If these are not present in your app's entitlements when you invoke, for example:
-
-```js title="main.js"
-const { systemPreferences } = require('electron')
-const microphone = systemPreferences.askForMediaAccess('microphone')
-```
-
-Your app may crash. See the Resource Access section in [Hardened Runtime](https://developer.apple.com/documentation/security/hardened_runtime) for more information and entitlements you may need.
-
-### Using Electron Builder
-
-Electron Builder comes with a custom solution for signing your application. You
-can find [its documentation here](https://www.electron.build/code-signing).
+Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos).
 
 ### Using Electron Packager
 
-If you're not using an integrated build pipeline like Forge or Builder, you
+If you're not using an integrated build pipeline like Forge, you
 are likely using [`electron-packager`], which includes [`electron-osx-sign`] and
 [`electron-notarize`].
 
@@ -204,36 +130,7 @@ commit it to your source code.
 
 ### Using Electron Forge
 
-Once you have a code signing certificate file (`.pfx`), you can sign
-[Squirrel.Windows][maker-squirrel] and [MSI][maker-msi] installers in Electron Forge
-with the `certificateFile` and `certificatePassword` fields in their respective
-configuration objects.
-
-For example, if you keep your Forge config in your `package.json` file and are
-creating a Squirrel.Windows installer:
-
-```json {9-15} title='package.json'
-{
-  "name": "my-app",
-  "version": "0.0.1",
-  //...
-  "config": {
-    "forge": {
-      "packagerConfig": {},
-      "makers": [
-        {
-          "name": "@electron-forge/maker-squirrel",
-          "config": {
-            "certificateFile": "./cert.pfx",
-            "certificatePassword": "this-is-a-secret"
-          }
-        }
-      ]
-    }
-  }
-  //...
-}
-```
+Electron Forge is the recommended way to sign your `Squirrel.Windows` and `WiX MSI` installers. Detailed instructions on how to configure your application can be found in the [Electron Forge Code Signing Tutorial](https://www.electronforge.io/guides/code-signing/code-signing-macos).
 
 ### Using electron-winstaller (Squirrel.Windows)
 

diff --git a/docs/tutorial/distribution-overview.md b/docs/tutorial/distribution-overview.md
@@ -11,7 +11,7 @@ you can deliver it to your users.
 ## Packaging
 
 To distribute your app with Electron, you need to package all your resources and assets
-into an executable and rebrand it. To do this, you can either use specialized tooling
+into an executable and rebrand it. To do this, you can either use specialized tooling like Electron Forge
 or do it manually. See the [Application Packaging][application-packaging] tutorial
 for more information.
 

diff --git a/docs/tutorial/forge-overview.md b/docs/tutorial/forge-overview.md
@@ -0,0 +1,36 @@
+# Distributing Apps With Electron Forge
+
+Electron Forge is a tool for packaging and publishing Electron applications.
+It unifies Electron's build tooling ecosystem into
+a single extensible interface so that anyone can jump right into making Electron apps.
+
+## Getting started
+
+The [Electron Forge docs] contain detailed information on taking your application
+from source code to your end users' machines.
+This includes:
+
+* Packaging your application [(package)]
+* Generating executables and installers for each OS [(make)], and,
+* Publishing these files to online platforms to download [(publish)].
+
+For beginners, we recommend following through Electron's [tutorial] to develop, build,
+package and publish your first Electron app. If you have already developed an app on your machine
+and want to start on packaging and distribution, start from [step 5] of the tutorial.
+
+## Getting help
+
+* If you need help with developing your app, our [community Discord server][discord] is a great place
+to get advice from other Electron app developers.
+* If you suspect you're running into a bug with Forge, please check the [GitHub issue tracker]
+to see if any existing issues match your problem. If not, feel free to fill out our bug report
+template and submit a new issue.
+
+[Electron Forge Docs]: https://www.electronforge.io/
+[step 5]: ./tutorial-5-packaging.md
+[(package)]: https://www.electronforge.io/cli#package
+[(make)]: https://www.electronforge.io/cli#make
+[(publish)]: https://www.electronforge.io/cli#publish
+[GitHub issue tracker]: https://github.com/electron-userland/electron-forge/issues
+[discord]: https://discord.gg/APGC3k5yaH
+[tutorial]: https://www.electronjs.org/docs/latest/tutorial/tutorial-prerequisites
diff --git a/docs/tutorial/tutorial-5-packaging.md b/docs/tutorial/tutorial-5-packaging.md
@@ -111,6 +111,12 @@ Electron Forge can be configured to create distributables in different OS-specif
 
 :::
 
+:::tip Creating and Adding Application Icons
+
+Setting custom application icons requires a few additions to your config. Check out [Forge's icon tutorial] for more information.
+
+:::
+
 :::note Packaging without Electron Forge
 
 If you want to manually package your code, or if you're just interested understanding the
@@ -214,6 +220,7 @@ information.
 [electron forge]: https://www.electronforge.io
 [electron forge cli documentation]: https://www.electronforge.io/cli#commands
 [makers]: https://www.electronforge.io/config/makers
+[Forge's icon tutorial]: https://www.electronforge.io/guides/create-and-add-icons
 
 <!-- Tutorial links -->