docs: Explain notarization, improve code-signing docs (#21373)

* docs: Explain notarization

* Update docs/tutorial/code-signing.md

Co-Authored-By: Zeke Sikelianos <[email protected]>

docs/tutorial/code-signing.md

@@ -3,7 +3,7 @@
 Code signing is a security technology that you use to certify that an app was
 created by you.
 
-On macOS the system can detect any change to the  app, whether the change is
+On macOS the system can detect any change to the app, whether the change is
 introduced accidentally or by malicious code.
 
 On Windows the system assigns a trust level to your code signing certificate which
@@ -11,15 +11,18 @@ if you don't have, or if your trust level is low will cause security dialogs to
 appear when users start using your application.  Trust level builds over time
 so it's better to start code signing as early as possible.
 
-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:
+While it is possible to distribute unsigned apps, it is not recommended. Both
+Windows and macOS will, by default, prevent either the download or the
+execution of unsigned applications. Starting with macOS Catalina (version 10.15),
+users have to go through multiple manual steps to open unsigned applications.
 
-![unsigned app warning on macOS](https://user-images.githubusercontent.com/2289/39488937-bdc854ba-4d38-11e8-88f8-7b3c125baefc.png)
+![macOS Catalina Gatekeeper warning: The app cannot be opened because the developer cannot be verified](../images/gatekeeper.png)
 
-> App can't be opened because it is from an unidentified developer
+As you can see, users get two options: Move the app straight to the trash or
+cancel running it. You don't want your users to see that dialog.
 
 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
+it should be code-signed. The Mac and Windows app stores do not allow unsigned
 apps.
 
 # Signing macOS builds
@@ -39,7 +42,20 @@ pass the `--osx-sign=true` flag to sign your build.
     in your forge config.
 - [`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].
+## Notarization
+
+Starting with macOS Catalina, Apple requires applications to be notarized.
+"Notarization" as defined by Apple means that you upload your previously signed
+application to Apple for additional verification _before_ distributing the app
+to your users.
+
+To automate this process, you can use the [`electron-notarize`] module. You
+do not necessarily need to complete this step for every build you make – just
+the builds you intend to ship to users.
+
+## Mac App Store
+
+See the [Mac App Store Guide].
 
 # Signing Windows builds
 
@@ -70,8 +86,9 @@ See the [Windows Store Guide].
 [`electron-forge`]: https://github.com/electron-userland/electron-forge
 [`electron-osx-sign`]: https://github.com/electron-userland/electron-osx-sign
 [`electron-packager`]: https://github.com/electron/electron-packager
+[`electron-notarize`]: https://github.com/electron/electron-notarize
 [`electron-winstaller`]: https://github.com/electron/windows-installer
 [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
+[signing certificates]: https://github.com/electron/electron-osx-sign/wiki/1.-Getting-Started#certificates
+[Mac App Store Guide]: mac-app-store-submission-guide.md
 [Windows Store Guide]: windows-store-guide.md