Bump v12.0.0-nightly.20201105

* fix: use parseInt to parse sizes

* fix: pass radix to parseInt

Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com>

Co-authored-by: Cheng Zhao <github@zcbenz.com>
Co-authored-by: Samuel Attard <samuel.r.attard@gmail.com>

.circleci/config.yml

@@ -107,6 +107,7 @@ env-release-build: &env-release-build
   STRIP_BINARIES: true
   GENERATE_SYMBOLS: true
   CHECK_DIST_MANIFEST: '1'
+  IS_RELEASE: true
 
 env-headless-testing: &env-headless-testing
   DISPLAY: ':99.0'
@@ -256,23 +257,34 @@ step-gclient-sync: &step-gclient-sync
           "$CIRCLE_REPOSITORY_URL"
 
         ELECTRON_USE_THREE_WAY_MERGE_FOR_PATCHES=1 gclient sync --with_branch_heads --with_tags
-        # Re-export all the patches to check if there were changes.
-        python src/electron/script/export_all_patches.py src/electron/patches/config.json
-        cd src/electron
-        git update-index --refresh || true
-        if ! git diff-index --quiet HEAD --; then
-          # There are changes to the patches. Make a git commit with the updated patches
-          git add patches
-          GIT_COMMITTER_NAME="Electron Bot" GIT_COMMITTER_EMAIL="anonymous@electronjs.org" git commit -m "update patches" --author="Electron Bot <anonymous@electronjs.org>"
-          # Export it
-          mkdir -p ../../patches
-          git format-patch -1 --stdout --keep-subject --no-stat --full-index > ../../patches/update-patches.patch
-          echo
-          echo "======================================================================"
-          echo "There were changes to the patches when applying."
-          echo "Check the CI artifacts for a patch you can apply to fix it."
-          echo "======================================================================"
-          exit 1
+        if [ "$IS_RELEASE" != "true" ]; then
+          # Re-export all the patches to check if there were changes.
+          python src/electron/script/export_all_patches.py src/electron/patches/config.json
+          cd src/electron
+          git update-index --refresh || true
+          if ! git diff-index --quiet HEAD --; then
+            # There are changes to the patches. Make a git commit with the updated patches
+            git add patches
+            GIT_COMMITTER_NAME="Electron Bot" GIT_COMMITTER_EMAIL="electron@github.com" git commit -m "update patches" --author="Electron Bot <electron@github.com>"
+            # Export it
+            mkdir -p ../../patches
+            git format-patch -1 --stdout --keep-subject --no-stat --full-index > ../../patches/update-patches.patch
+            if (node ./script/push-patch.js 2> /dev/null > /dev/null); then
+              echo
+              echo "======================================================================"
+              echo "Changes to the patches when applying, we have auto-pushed the diff to the current branch"
+              echo "A new CI job will kick off shortly"
+              echo "======================================================================"
+              exit 1
+            else
+              echo
+              echo "======================================================================"
+              echo "There were changes to the patches when applying."
+              echo "Check the CI artifacts for a patch you can apply to fix it."
+              echo "======================================================================"
+              exit 1
+            fi
+          fi
         fi
       fi
 
@@ -572,6 +584,9 @@ step-electron-dist-build: &step-electron-dist-build
             if [ x"$MAS_BUILD" == x"true" ]; then
               target_os=mac_mas
             fi
+            if [ "$TARGET_ARCH" == "arm64" ]; then
+              target_cpu=arm64
+            fi
           elif [ "`uname`" == "Linux" ]; then
             target_os=linux
             if [ x"$TARGET_ARCH" == x ]; then
@@ -764,14 +779,20 @@ step-setup-linux-for-headless-testing: &step-setup-linux-for-headless-testing
 
 step-show-sccache-stats: &step-show-sccache-stats
   run:
+    shell: /bin/bash
     name: Check sccache/goma stats after build
     command: |
       if [ "$SCCACHE_PATH" != "" ]; then
         $SCCACHE_PATH -s
       fi
       if [ "$USE_GOMA" == "true" ]; then
+        set +e
+        set +o pipefail
         $LOCAL_GOMA_DIR/goma_ctl.py stat
+        $LOCAL_GOMA_DIR/diagnose_goma_log.py
+        true
       fi
+    when: always
 
 step-mksnapshot-build: &step-mksnapshot-build
   run:
@@ -1796,7 +1817,7 @@ jobs:
 
   # Layer 2: Builds.
   linux-x64-testing:
-    <<: *machine-linux-xlarge
+    <<: *machine-linux-2xlarge
     environment:
       <<: *env-global
       <<: *env-testing-build
@@ -1876,7 +1897,7 @@ jobs:
           checkout: false
 
   linux-ia32-testing:
-    <<: *machine-linux-xlarge
+    <<: *machine-linux-2xlarge
     environment:
       <<: *env-global
       <<: *env-ia32

.eslintrc.json

@@ -8,9 +8,9 @@
   "rules": {
     "semi": ["error", "always"],
     "no-var": "error",
-    "no-unused-vars": 0,
-    "no-global-assign": 0,
-    "guard-for-in": 2,
+    "no-unused-vars": "off",
+    "no-global-assign": "off",
+    "guard-for-in": "error",
     "@typescript-eslint/no-unused-vars": ["error", {
       "vars": "all",
       "args": "after-used",
@@ -20,33 +20,33 @@
       "destructuring": "all"
     }],
     "standard/no-callback-literal": "off",
-    "node/no-deprecated-api": 0
+    "node/no-deprecated-api": "off"
   },
   "parserOptions": {
     "ecmaVersion": 6,
     "sourceType": "module"
   },
-  "globals": {
-    "standardScheme": "readonly",
-    "globalThis": "readonly",
-    "BUILDFLAG": "readonly",
-    "ENABLE_DESKTOP_CAPTURER": "readonly",
-    "ENABLE_REMOTE_MODULE": "readonly",
-    "ENABLE_VIEWS_API": "readonly",
-    "BigInt": "readonly"
-  },
   "overrides": [
     {
       "files": "*.js",
       "rules": {
-          "@typescript-eslint/no-unused-vars": "off"
+        "@typescript-eslint/no-unused-vars": "off"
+      }
+    },
+    {
+      "files": "*.ts",
+      "rules": {
+        "no-undef": "off",
+        "no-redeclare": "off",
+        "@typescript-eslint/no-redeclare": ["error"],
+        "no-use-before-define": "off"
       }
     },
     {
       "files": "*.d.ts",
       "rules": {
-          "no-useless-constructor": "off",
-          "@typescript-eslint/no-unused-vars": "off"
+        "no-useless-constructor": "off",
+        "@typescript-eslint/no-unused-vars": "off"
       }
     }
   ]

.github/PULL_REQUEST_TEMPLATE.md

@@ -13,7 +13,6 @@ Contributors guide: https://github.com/electron/electron/blob/master/CONTRIBUTIN
 - [ ] `npm test` passes
 - [ ] tests are [changed or added](https://github.com/electron/electron/blob/master/docs/development/testing.md)
 - [ ] relevant documentation is changed or added
-- [ ] PR title follows semantic [commit guidelines](https://github.com/electron/electron/blob/master/docs/development/pull-requests.md#commit-message-guidelines)
 - [ ] [PR release notes](https://github.com/electron/clerk/blob/master/README.md) describe the change in a way relevant to app developers, and are [capitalized, punctuated, and past tense](https://github.com/electron/clerk/blob/master/README.md#examples).
 
 #### Release Notes

.gitignore

@@ -65,4 +65,7 @@ ts-gen
 
 # Used to accelerate CI builds
 .depshash
-.depshash-target
+.depshash-target
+
+# Used to accelerate builds after sync
+patches/mtime-cache.json

BUILD.gn

@@ -184,7 +184,6 @@ target_gen_default_app_js = "$target_gen_dir/js/default_app"
 
 typescript_build("default_app_js") {
   deps = [ ":build_electron_definitions" ]
-  type_root = rebase_path("$target_gen_dir/tsc/electron/typings")
 
   sources = filenames.default_app_ts_sources
 
@@ -303,6 +302,19 @@ templated_file("electron_version_header") {
   args_files = get_target_outputs(":electron_version_args")
 }
 
+action("electron_fuses") {
+  script = "build/fuses/build.py"
+
+  inputs = [ "build/fuses/fuses.json" ]
+
+  outputs = [
+    "$target_gen_dir/fuses.h",
+    "$target_gen_dir/fuses.cc",
+  ]
+
+  args = rebase_path(outputs)
+}
+
 source_set("electron_lib") {
   configs += [ "//v8:external_startup_data" ]
   configs += [ "//third_party/electron_node:node_internals" ]
@@ -313,6 +325,7 @@ source_set("electron_lib") {
   ]
 
   deps = [
+    ":electron_fuses",
     ":electron_js2c",
     ":electron_version_header",
     ":manifests",
@@ -325,7 +338,6 @@ source_set("electron_lib") {
     "//base/allocator:buildflags",
     "//chrome/app:command_ids",
     "//chrome/app/resources:platform_locale_settings",
-    "//chrome/services/printing/public/mojom",
     "//components/certificate_transparency",
     "//components/language/core/browser",
     "//components/net_log",
@@ -372,6 +384,7 @@ source_set("electron_lib") {
     "//third_party/libyuv",
     "//third_party/webrtc_overrides:webrtc_component",
     "//third_party/widevine/cdm:headers",
+    "//third_party/zlib/google:zip",
     "//ui/base/idle",
     "//ui/events:dom_keycode_converter",
     "//ui/gl",
@@ -405,44 +418,26 @@ source_set("electron_lib") {
     defines += [ "GDK_DISABLE_DEPRECATION_WARNINGS" ]
   }
 
-  extra_source_filters = []
-  if (!is_linux) {
-    extra_source_filters += [
-      "*\bx/*",
-      "*_x11.h",
-      "*_x11.cc",
-      "*_gtk.h",
-      "*_gtk.cc",
-      "*\blibrary_loaders/*",
-    ]
-  }
-  if (!is_win) {
-    extra_source_filters += [
-      "*\bwin_*.h",
-      "*\bwin_*.cc",
-    ]
-  }
-  if (!is_posix) {
-    extra_source_filters += [
-      "*_posix.cc",
-      "*_posix.h",
-    ]
-  }
-  if (is_mac) {
-    extra_source_filters += [
-      "*_views.cc",
-      "*_views.h",
-      "*\bviews/*",
-    ]
-  }
   if (!is_mas_build) {
     deps += [ "//components/crash/core/app" ]
   }
 
-  set_sources_assignment_filter(
-      sources_assignment_filter + extra_source_filters)
   sources = filenames.lib_sources
-  set_sources_assignment_filter(sources_assignment_filter)
+  if (is_win) {
+    sources += filenames.lib_sources_win
+  }
+  if (is_mac) {
+    sources += filenames.lib_sources_mac
+  }
+  if (is_posix) {
+    sources += filenames.lib_sources_posix
+  }
+  if (is_linux) {
+    sources += filenames.lib_sources_linux
+  }
+  if (!is_mac) {
+    sources += filenames.lib_sources_views
+  }
 
   if (is_component_build) {
     defines += [ "NODE_SHARED_MODE" ]
@@ -525,15 +520,13 @@ source_set("electron_lib") {
       "//ui/wm",
     ]
     if (use_x11) {
+      sources += filenames.lib_sources_linux_x11
       deps += [
         "//ui/gfx/x",
         "//ui/gtk/x",
       ]
     }
     configs += [ ":gio_unix" ]
-    if (use_x11) {
-      deps += [ "//ui/gfx/x" ]
-    }
     defines += [
       # Disable warnings for g_settings_list_schemas.
       "GLIB_DISABLE_DEPRECATION_WARNINGS",
@@ -589,7 +582,6 @@ source_set("electron_lib") {
     sources += [
       "shell/browser/osr/osr_host_display_client.cc",
       "shell/browser/osr/osr_host_display_client.h",
-      "shell/browser/osr/osr_host_display_client_mac.mm",
       "shell/browser/osr/osr_render_widget_host_view.cc",
       "shell/browser/osr/osr_render_widget_host_view.h",
       "shell/browser/osr/osr_video_consumer.cc",
@@ -598,8 +590,13 @@ source_set("electron_lib") {
       "shell/browser/osr/osr_view_proxy.h",
       "shell/browser/osr/osr_web_contents_view.cc",
       "shell/browser/osr/osr_web_contents_view.h",
-      "shell/browser/osr/osr_web_contents_view_mac.mm",
     ]
+    if (is_mac) {
+      sources += [
+        "shell/browser/osr/osr_host_display_client_mac.mm",
+        "shell/browser/osr/osr_web_contents_view_mac.mm",
+      ]
+    }
     deps += [
       "//components/viz/service",
       "//services/viz/public/mojom",
@@ -634,7 +631,10 @@ source_set("electron_lib") {
       "shell/renderer/printing/print_render_frame_helper_delegate.cc",
       "shell/renderer/printing/print_render_frame_helper_delegate.h",
     ]
-    deps += [ "//components/printing/common:mojo_interfaces" ]
+    deps += [
+      "//chrome/services/printing/public/mojom",
+      "//components/printing/common:mojo_interfaces",
+    ]
   }
 
   if (enable_electron_extensions) {
@@ -673,6 +673,16 @@ source_set("electron_lib") {
       "shell/browser/electron_pdf_web_contents_helper_client.h",
     ]
   }
+
+  sources += get_target_outputs(":electron_fuses")
+
+  if (is_win && enable_win_dark_mode_window_ui) {
+    sources += [
+      "shell/browser/win/dark_mode.cc",
+      "shell/browser/win/dark_mode.h",
+    ]
+    libs += [ "uxtheme.lib" ]
+  }
 }
 
 electron_paks("packed_resources") {
@@ -698,10 +708,10 @@ if (is_mac) {
   action("fake_v8_context_snapshot_generator") {
     script = "build/fake_v8_context_snapshot_generator.py"
     args = [
-      rebase_path("$root_out_dir/v8_context_snapshot.bin"),
-      rebase_path("$root_out_dir/fake/v8_context_snapshot.bin"),
+      rebase_path("$root_out_dir/$v8_context_snapshot_filename"),
+      rebase_path("$root_out_dir/fake/$v8_context_snapshot_filename"),
     ]
-    outputs = [ "$root_out_dir/fake/v8_context_snapshot.bin" ]
+    outputs = [ "$root_out_dir/fake/$v8_context_snapshot_filename" ]
   }
 
   bundle_data("electron_framework_resources") {
@@ -715,10 +725,10 @@ if (is_mac) {
       public_deps += [ "//v8" ]
       if (use_v8_context_snapshot) {
         if (use_prebuilt_v8_context_snapshot) {
-          sources += [ "$root_out_dir/fake/v8_context_snapshot.bin" ]
+          sources += [ "$root_out_dir/fake/$v8_context_snapshot_filename" ]
           public_deps += [ ":fake_v8_context_snapshot_generator" ]
         } else {
-          sources += [ "$root_out_dir/v8_context_snapshot.bin" ]
+          sources += [ "$root_out_dir/$v8_context_snapshot_filename" ]
           public_deps += [ "//tools/v8_context_snapshot" ]
         }
       } else {

DEPS

@@ -14,9 +14,9 @@ gclient_gn_args = [
 
 vars = {
   'chromium_version':
-    'b943d006a33ec5bc1743792d64724693eb357083',
+    '2a55c4f55b99b2191ea59cba1e2f6da4dbb7dee0',
   'node_version':
-    'v14.13.1',
+    'v14.15.0',
   'nan_version':
     '2c4ee8a32a299eada3cd6e468bbd0a473bfea96d',
   'squirrel.mac_version':
@@ -38,6 +38,9 @@ vars = {
   # To be able to build clean Chromium from sources.
   'apply_patches': True,
 
+  # To use an mtime cache for patched files to speed up builds.
+  'use_mtime_cache': True,
+
   # To allow in-house builds to checkout those manually.
   'checkout_chromium': True,
   'checkout_node': True,
@@ -75,6 +78,8 @@ vars = {
     False,
   'checkout_google_benchmark':
     False,
+  'checkout_clang_tidy':
+    True,
 }
 
 deps = {
@@ -112,6 +117,23 @@ deps = {
   }
 }
 
+pre_deps_hooks = [
+  {
+    'name': 'generate_mtime_cache',
+    'condition': '(checkout_chromium and apply_patches and use_mtime_cache) and process_deps',
+    'pattern': 'src/electron',
+    'action': [
+      'python3',
+      'src/electron/script/patches-mtime-cache.py',
+      'generate',
+      '--cache-file',
+      'src/electron/patches/mtime-cache.json',
+      '--patches-config',
+      'src/electron/patches/config.json',
+    ],
+  },
+]
+
 hooks = [
   {
     'name': 'patch_chromium',
@@ -123,6 +145,18 @@ hooks = [
       'src/electron/patches/config.json',
     ],
   },
+  {
+    'name': 'apply_mtime_cache',
+    'condition': '(checkout_chromium and apply_patches and use_mtime_cache) and process_deps',
+    'pattern': 'src/electron',
+    'action': [
+      'python3',
+      'src/electron/script/patches-mtime-cache.py',
+      'apply',
+      '--cache-file',
+      'src/electron/patches/mtime-cache.json',
+    ],
+  },
   {
     'name': 'electron_external_binaries',
     'pattern': 'src/electron/script/update-external-binaries.py',

ELECTRON_VERSION

@@ -1 +1 @@
-12.0.0-nightly.20201013
+12.0.0-nightly.20201105

appveyor.yml

@@ -66,7 +66,6 @@ build_script:
   - update_depot_tools.bat
   - ps: Move-Item $env:APPVEYOR_BUILD_FOLDER -Destination src\electron
   - ps: $env:CHROMIUM_BUILDTOOLS_PATH="$pwd\src\buildtools"
-  - ps: $env:SCCACHE_PATH="$pwd\src\electron\external_binaries\sccache.exe"
   - ps: >-
       if ($env:GN_CONFIG -eq 'release') {
         $env:GCLIENT_EXTRA_ARGS="$env:GCLIENT_EXTRA_ARGS --custom-var=checkout_requests=True"
@@ -101,6 +100,11 @@ build_script:
           } else {
             # update external binaries
             python src/electron/script/update-external-binaries.py
+            # update angle
+            cd src\third_party\angle
+            git remote set-url origin  https://chromium.googlesource.com/angle/angle.git
+            git fetch
+            cd ..\..\..
           }
         } else {    
           # file does not exist, gclient sync, then zip
@@ -116,35 +120,35 @@ build_script:
       if ($env:SAVE_GCLIENT_SRC -eq 'true') {
         # archive current source for future use 
         # only run on x64/woa to avoid contention saving
-        if ($(7z a $zipfile src -xr!android_webview -xr!electron -xr'!*\.git' -xr!third_party\WebKit\LayoutTests! -xr!third_party\blink\web_tests -xr!third_party\blink\perf_tests -slp -t7z -mmt=30;$LASTEXITCODE -ne 0)) {
+        $(7z a $zipfile src -xr!android_webview -xr!electron -xr'!*\.git' -xr!third_party\WebKit\LayoutTests! -xr!third_party\blink\web_tests -xr!third_party\blink\perf_tests -slp -t7z -mmt=30)
+        if ($LASTEXITCODE -ne 0) {
           Write-warning "Could not save source to shared drive; continuing anyway"
         }
-        # build time generation of file gen/angle/commit.h depends on
-        # third_party/angle/.git/HEAD.
-        # https://chromium-review.googlesource.com/c/angle/angle/+/2074924
-        if ($(7z a $zipfile src\third_party\angle\.git\HEAD;$LASTEXITCODE -ne 0)) {
-          Write-warning "Failed to add third_party\angle\.git\HEAD; continuing anyway"
+        # build time generation of file gen/angle/angle_commit.h depends on
+        # third_party/angle/.git
+        # https://chromium-review.googlesource.com/c/angle/angle/+/2074924       
+        $(7z a $zipfile src\third_party\angle\.git)
+        if ($LASTEXITCODE -ne 0) {
+          Write-warning "Failed to add third_party\angle\.git; continuing anyway"
         }
       }
   - ps: >-
-      if ($env:GN_CONFIG -ne 'release') {
-        if (Test-Path 'env:RAW_GOMA_AUTH') {
-          $env:GOMA_OAUTH2_CONFIG_FILE = "$pwd\.goma_oauth2_config"
-          $env:RAW_GOMA_AUTH | Set-Content $env:GOMA_OAUTH2_CONFIG_FILE      
-        }
-        git clone https://github.com/electron/build-tools.git
-        cd build-tools
-        npm install
-        mkdir third_party
-        node -e "require('./src/utils/goma.js').downloadAndPrepare()"
-        $env:GN_GOMA_FILE = node -e "console.log(require('./src/utils/goma.js').gnFilePath)"
-        $env:LOCAL_GOMA_DIR = node -e "console.log(require('./src/utils/goma.js').dir)"
-        cd ..
-        .\src\electron\script\start-goma.ps1 -gomaDir $env:LOCAL_GOMA_DIR
+      if (Test-Path 'env:RAW_GOMA_AUTH') {
+        $env:GOMA_OAUTH2_CONFIG_FILE = "$pwd\.goma_oauth2_config"
+        $env:RAW_GOMA_AUTH | Set-Content $env:GOMA_OAUTH2_CONFIG_FILE
       }
+  - git clone https://github.com/electron/build-tools.git
+  - cd build-tools
+  - npm install
+  - mkdir third_party
+  - node -e "require('./src/utils/goma.js').downloadAndPrepare()"
+  - ps: $env:GN_GOMA_FILE = node -e "console.log(require('./src/utils/goma.js').gnFilePath)"
+  - ps: $env:LOCAL_GOMA_DIR = node -e "console.log(require('./src/utils/goma.js').dir)"
+  - cd ..
+  - ps: .\src\electron\script\start-goma.ps1 -gomaDir $env:LOCAL_GOMA_DIR
   - cd src
   - set BUILD_CONFIG_PATH=//electron/build/args/%GN_CONFIG%.gn 
-  - if DEFINED GN_GOMA_FILE (gn gen out/Default "--args=import(\"%BUILD_CONFIG_PATH%\") import(\"%GN_GOMA_FILE%\") %GN_EXTRA_ARGS% ") else (gn gen out/Default "--args=import(\"%BUILD_CONFIG_PATH%\") %GN_EXTRA_ARGS% cc_wrapper=\"%SCCACHE_PATH%\"")
+  - gn gen out/Default "--args=import(\"%BUILD_CONFIG_PATH%\") import(\"%GN_GOMA_FILE%\") %GN_EXTRA_ARGS% "
   - gn check out/Default //electron:electron_lib
   - gn check out/Default //electron:electron_app
   - gn check out/Default //electron:manifests
@@ -163,7 +167,7 @@ build_script:
   - ninja -C out/Default electron:hunspell_dictionaries_zip
   - ninja -C out/Default electron:electron_chromedriver_zip
   - ninja -C out/Default third_party/electron_node:headers
-  - if "%GN_CONFIG%"=="testing" ( python %LOCAL_GOMA_DIR%\goma_ctl.py stat )
+  - python %LOCAL_GOMA_DIR%\goma_ctl.py stat
   - python electron/build/profile_toolchain.py --output-json=out/Default/windows_toolchain_profile.json
   - appveyor PushArtifact out/Default/windows_toolchain_profile.json
   - appveyor PushArtifact out/Default/dist.zip
@@ -207,7 +211,8 @@ test_script:
         echo "Skipping tests for $env:GN_CONFIG build"
       }
   - cd electron
-  - if "%RUN_TESTS%"=="true" ( echo Running test suite & node script/yarn test -- --trace-uncaught --enable-logging)
+  # CalculateNativeWinOcclusion is disabled due to https://bugs.chromium.org/p/chromium/issues/detail?id=1139022
+  - if "%RUN_TESTS%"=="true" ( echo Running test suite & node script/yarn test -- --trace-uncaught --enable-logging --disable-features=CalculateNativeWinOcclusion )
   - cd ..
   - if "%RUN_TESTS%"=="true" ( echo Verifying non proprietary ffmpeg & python electron\script\verify-ffmpeg.py --build-dir out\Default --source-root %cd% --ffmpeg-path out\ffmpeg )
   - echo "About to verify mksnapshot"

azure-pipelines-woa.yml

@@ -63,7 +63,8 @@ steps:
     set npm_config_nodedir=%cd%\out\Default\gen\node_headers
     set npm_config_arch=arm64
     cd electron
-    node script/yarn test -- --enable-logging --verbose
+    # CalculateNativeWinOcclusion is disabled due to https://bugs.chromium.org/p/chromium/issues/detail?id=1139022
+    node script/yarn test -- --enable-logging --verbose --disable-features=CalculateNativeWinOcclusion
   displayName: 'Run Electron tests'
   env:
     ELECTRON_OUT_DIR: Default

build/fuses/build.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+
+import json
+import os
+import sys
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+
+SENTINEL = "dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX"
+
+TEMPLATE_H = """
+#ifndef ELECTRON_FUSES_H_
+#define ELECTRON_FUSES_H_
+
+#if defined(WIN32)
+#define FUSE_EXPORT __declspec(dllexport)
+#else
+#define FUSE_EXPORT __attribute__((visibility("default")))
+#endif
+
+namespace electron {
+
+namespace fuses {
+
+extern const volatile char kFuseWire[];
+
+{getters}
+
+}  // namespace fuses
+
+}  // namespace electron
+
+#endif  // ELECTRON_FUSES_H_
+"""
+
+TEMPLATE_CC = """
+#include "electron/fuses.h"
+
+namespace electron {
+
+namespace fuses {
+
+const volatile char kFuseWire[] = { /* sentinel */ {sentinel}, /* fuse_version */ {fuse_version}, /* fuse_wire_length */ {fuse_wire_length}, /* fuse_wire */ {initial_config}};
+
+{getters}
+
+}
+
+}
+"""
+
+with open(os.path.join(dir_path, "fuses.json"), 'r') as f:
+  fuse_defaults = json.load(f)
+
+fuse_version = fuse_defaults['_version']
+del fuse_defaults['_version']
+del fuse_defaults['_schema']
+del fuse_defaults['_comment']
+
+if fuse_version >= pow(2, 8):
+  raise Exception("Fuse version can not exceed one byte in size")
+
+fuses = fuse_defaults.keys()
+
+initial_config = ""
+getters_h = ""
+getters_cc = ""
+index = len(SENTINEL) + 1
+for fuse in fuses:
+  index += 1
+  initial_config += fuse_defaults[fuse]
+  name = ''.join(word.title() for word in fuse.split('_'))
+  getters_h += "FUSE_EXPORT bool Is{name}Enabled();\n".replace("{name}", name)
+  getters_cc += """
+bool Is{name}Enabled() {
+  return kFuseWire[{index}] == '1';
+}
+""".replace("{name}", name).replace("{index}", str(index))
+
+def c_hex(n):
+  s = hex(n)[2:]
+  return "0x" + s.rjust(2, '0')
+
+def hex_arr(s):
+  arr = []
+  for char in s:
+    arr.append(c_hex(ord(char)))
+  return ",".join(arr)
+
+header = TEMPLATE_H.replace("{getters}", getters_h.strip())
+impl = TEMPLATE_CC.replace("{sentinel}", hex_arr(SENTINEL))
+impl = impl.replace("{fuse_version}", c_hex(fuse_version))
+impl = impl.replace("{fuse_wire_length}", c_hex(len(fuses)))
+impl = impl.replace("{initial_config}", hex_arr(initial_config))
+impl = impl.replace("{getters}", getters_cc.strip())
+
+with open(sys.argv[1], 'w') as f:
+  f.write(header)
+
+with open(sys.argv[2], 'w') as f:
+  f.write(impl)

build/fuses/fuses.json

@@ -0,0 +1,6 @@
+{
+  "_comment": "Modifying the fuse schema in any breaking way should result in the _version prop being incremented.  NEVER remove a fuse or change its meaning, instead mark it as removed with 'r'",
+  "_schema": "0 == off, 1 == on, r == removed fuse",
+  "_version": 1,
+  "run_as_node": "1"
+}

build/npm-run.py

@@ -15,5 +15,12 @@ args = [cmd, "run",
 try:
     subprocess.check_output(args, stderr=subprocess.STDOUT)
 except subprocess.CalledProcessError as e:
-    print("NPM script '" + sys.argv[2] + "' failed with code '" + str(e.returncode) + "':\n" + e.output)
+    print(
+        "NPM script '"
+        + sys.argv[2]
+        + "' failed with code '"
+        + str(e.returncode)
+        + "':\n"
+        + e.output
+    )
     sys.exit(e.returncode)

build/profile_toolchain.py

@@ -19,10 +19,10 @@ from get_toolchain_if_necessary import CalculateHash
 
 
 @contextlib.contextmanager
-def cwd(dir):
+def cwd(directory):
     curdir = os.getcwd()
     try:
-        os.chdir(dir)
+        os.chdir(directory)
         yield
     finally:
         os.chdir(curdir)
@@ -70,12 +70,18 @@ def windows_profile():
     win_sdk_dir = SetEnvironmentAndGetSDKDir()
     path = NormalizePath(os.environ['GYP_MSVS_OVERRIDE_PATH'])
 
+    # since current windows executable are symbols path dependant,
+    # profile the current directory too
     return {
-        'pwd': os.getcwd(), # since current windows executable are symbols path dependant, profile the current directory too
+        'pwd': os.getcwd(),
         'installed_software': windows_installed_software(),
         'sdks': [
             {'name': 'vs', 'path': path, 'hash': calculate_hash(path)},
-            {'name': 'wsdk', 'path': win_sdk_dir, 'hash': calculate_hash(win_sdk_dir)}
+            {
+                'name': 'wsdk',
+                'path': win_sdk_dir,
+                'hash': calculate_hash(win_sdk_dir),
+            },
         ],
         'runtime_lib_dirs': runtime_dll_dirs,
     }
@@ -93,5 +99,5 @@ if __name__ == '__main__':
   parser = optparse.OptionParser()
   parser.add_option('--output-json', metavar='FILE', default='profile.json',
                     help='write information about toolchain to FILE')
-  options, args = parser.parse_args()
-  sys.exit(main(options))
+  opts, args = parser.parse_args()
+  sys.exit(main(opts))

build/strip_framework.py

@@ -12,5 +12,7 @@ subprocess.check_output(["rm", "-rf", dest])
 subprocess.check_output(["cp", "-a", source, dest])
 
 # Strip headers, we do not need to ship them
-subprocess.check_output(["rm", "-r", os.path.join(dest, 'Headers')])
-subprocess.check_output(["rm", "-r", os.path.join(dest, 'Versions', 'Current', 'Headers')])
+subprocess.check_output(["rm", "-r", os.path.join(dest, "Headers")])
+subprocess.check_output(
+    ["rm", "-r", os.path.join(dest, "Versions", "Current", "Headers")]
+)

build/tsc.gni

@@ -26,19 +26,12 @@ template("typescript_build") {
       "//electron/typings/internal-electron.d.ts",
     ]
 
-    type_roots = "node_modules/@types,typings"
-    if (defined(invoker.type_root)) {
-      type_roots += "," + invoker.type_root
-    }
-
     base_out_path = invoker.output_gen_dir + "/electron/"
     args = [
       "-p",
       rebase_path(invoker.tsconfig),
       "--outDir",
       rebase_path("$base_out_path" + invoker.output_dir_name),
-      "--typeRoots",
-      type_roots,
     ]
 
     outputs = []

build/webpack/get-outputs.js

@@ -1,2 +0,0 @@
-process.env.PRINT_WEBPACK_GRAPH = true;
-require('./run-compiler');

build/webpack/run-compiler.js

@@ -1,45 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-const webpack = require('webpack');
-
-const configPath = process.argv[2];
-const outPath = path.resolve(process.argv[3]);
-const config = require(configPath);
-config.output = {
-  path: path.dirname(outPath),
-  filename: path.basename(outPath)
-};
-
-const { wrapInitWithProfilingTimeout, wrapInitWithTryCatch, ...webpackConfig } = config;
-
-webpack(webpackConfig, (err, stats) => {
-  if (err) {
-    console.error(err);
-    process.exit(1);
-  } else if (stats.hasErrors()) {
-    console.error(stats.toString('normal'));
-    process.exit(1);
-  } else {
-    let contents = fs.readFileSync(outPath, 'utf8');
-    if (wrapInitWithTryCatch) {
-      contents = `try {
-${contents}
-} catch (err) {
-  console.error('Electron ${webpackConfig.output.filename} script failed to run');
-  console.error(err);
-}`;
-    }
-    if (wrapInitWithProfilingTimeout) {
-      contents = `function ___electron_webpack_init__() {
-${contents}
-};
-if ((globalThis.process || binding.process).argv.includes("--profile-electron-init")) {
-  setTimeout(___electron_webpack_init__, 0);
-} else {
-  ___electron_webpack_init__();
-}`;
-    }
-    fs.writeFileSync(outPath, contents);
-    process.exit(0);
-  }
-});

build/webpack/webpack.config.base.js

@@ -2,16 +2,12 @@ const fs = require('fs');
 const path = require('path');
 const webpack = require('webpack');
 const TerserPlugin = require('terser-webpack-plugin');
+const WrapperPlugin = require('wrapper-webpack-plugin');
 
 const electronRoot = path.resolve(__dirname, '../..');
 
-const onlyPrintingGraph = !!process.env.PRINT_WEBPACK_GRAPH;
-
 class AccessDependenciesPlugin {
   apply (compiler) {
-    // Only hook into webpack when we are printing the dependency graph
-    if (!onlyPrintingGraph) return;
-
     compiler.hooks.compilation.tap('AccessDependenciesPlugin', compilation => {
       compilation.hooks.finishModules.tap('AccessDependenciesPlugin', modules => {
         const filePaths = modules.map(m => m.resource).filter(p => p).map(p => path.relative(electronRoot, p));
@@ -21,49 +17,6 @@ class AccessDependenciesPlugin {
   }
 }
 
-const defines = {
-  BUILDFLAG: onlyPrintingGraph ? '(a => a)' : ''
-};
-
-const buildFlagsPrefix = '--buildflags=';
-const buildFlagArg = process.argv.find(arg => arg.startsWith(buildFlagsPrefix));
-
-if (buildFlagArg) {
-  const buildFlagPath = buildFlagArg.substr(buildFlagsPrefix.length);
-
-  const flagFile = fs.readFileSync(buildFlagPath, 'utf8');
-  for (const line of flagFile.split(/(\r\n|\r|\n)/g)) {
-    const flagMatch = line.match(/#define BUILDFLAG_INTERNAL_(.+?)\(\) \(([01])\)/);
-    if (flagMatch) {
-      const [, flagName, flagValue] = flagMatch;
-      defines[flagName] = JSON.stringify(Boolean(parseInt(flagValue, 10)));
-    }
-  }
-}
-
-const ignoredModules = [];
-
-if (defines.ENABLE_DESKTOP_CAPTURER === 'false') {
-  ignoredModules.push(
-    '@electron/internal/browser/desktop-capturer',
-    '@electron/internal/browser/api/desktop-capturer',
-    '@electron/internal/renderer/api/desktop-capturer'
-  );
-}
-
-if (defines.ENABLE_REMOTE_MODULE === 'false') {
-  ignoredModules.push(
-    '@electron/internal/browser/remote/server',
-    '@electron/internal/renderer/api/remote'
-  );
-}
-
-if (defines.ENABLE_VIEWS_API === 'false') {
-  ignoredModules.push(
-    '@electron/internal/browser/api/views/image-view.js'
-  );
-}
-
 module.exports = ({
   alwaysHasNode,
   loadElectronFromAlternateTarget,
@@ -79,76 +32,148 @@ module.exports = ({
 
   const electronAPIFile = path.resolve(electronRoot, 'lib', loadElectronFromAlternateTarget || target, 'api', 'exports', 'electron.ts');
 
-  return ({
-    mode: 'development',
-    devtool: false,
-    entry,
-    target: alwaysHasNode ? 'node' : 'web',
-    output: {
-      filename: `${target}.bundle.js`
-    },
-    wrapInitWithProfilingTimeout,
-    wrapInitWithTryCatch,
-    resolve: {
-      alias: {
-        '@electron/internal': path.resolve(electronRoot, 'lib'),
-        electron$: electronAPIFile,
-        'electron/main$': electronAPIFile,
-        'electron/renderer$': electronAPIFile,
-        'electron/common$': electronAPIFile,
-        // Force timers to resolve to our dependency that doesn't use window.postMessage
-        timers: path.resolve(electronRoot, 'node_modules', 'timers-browserify', 'main.js')
-      },
-      extensions: ['.ts', '.js']
-    },
-    module: {
-      rules: [{
-        test: (moduleName) => !onlyPrintingGraph && ignoredModules.includes(moduleName),
-        loader: 'null-loader'
-      }, {
-        test: /\.ts$/,
-        loader: 'ts-loader',
-        options: {
-          configFile: path.resolve(electronRoot, 'tsconfig.electron.json'),
-          transpileOnly: onlyPrintingGraph,
-          ignoreDiagnostics: [
-            // File '{0}' is not under 'rootDir' '{1}'.
-            6059
-          ]
+  return (env = {}, argv = {}) => {
+    const onlyPrintingGraph = !!env.PRINT_WEBPACK_GRAPH;
+    const outputFilename = argv['output-filename'] || `${target}.bundle.js`;
+
+    const defines = {
+      BUILDFLAG: onlyPrintingGraph ? '(a => a)' : ''
+    };
+
+    if (env.buildflags) {
+      const flagFile = fs.readFileSync(env.buildflags, 'utf8');
+      for (const line of flagFile.split(/(\r\n|\r|\n)/g)) {
+        const flagMatch = line.match(/#define BUILDFLAG_INTERNAL_(.+?)\(\) \(([01])\)/);
+        if (flagMatch) {
+          const [, flagName, flagValue] = flagMatch;
+          defines[flagName] = JSON.stringify(Boolean(parseInt(flagValue, 10)));
         }
-      }]
-    },
-    node: {
-      __dirname: false,
-      __filename: false,
-      // We provide our own "timers" import above, any usage of setImmediate inside
-      // one of our renderer bundles should import it from the 'timers' package
-      setImmediate: false
-    },
-    optimization: {
-      minimize: true,
-      minimizer: [
-        new TerserPlugin({
-          terserOptions: {
-            keep_classnames: true,
-            keep_fnames: true
-          }
-        })
-      ]
-    },
-    plugins: [
-      new AccessDependenciesPlugin(),
-      ...(targetDeletesNodeGlobals ? [
-        new webpack.ProvidePlugin({
-          process: ['@electron/internal/common/webpack-provider', 'process'],
-          global: ['@electron/internal/common/webpack-provider', '_global'],
-          Buffer: ['@electron/internal/common/webpack-provider', 'Buffer']
-        })
-      ] : []),
-      new webpack.ProvidePlugin({
-        Promise: ['@electron/internal/common/webpack-globals-provider', 'Promise']
-      }),
-      new webpack.DefinePlugin(defines)
-    ]
-  });
+      }
+    }
+
+    const ignoredModules = [];
+
+    if (defines.ENABLE_DESKTOP_CAPTURER === 'false') {
+      ignoredModules.push(
+        '@electron/internal/browser/desktop-capturer',
+        '@electron/internal/browser/api/desktop-capturer',
+        '@electron/internal/renderer/api/desktop-capturer'
+      );
+    }
+
+    if (defines.ENABLE_REMOTE_MODULE === 'false') {
+      ignoredModules.push(
+        '@electron/internal/browser/remote/server',
+        '@electron/internal/renderer/api/remote'
+      );
+    }
+
+    if (defines.ENABLE_VIEWS_API === 'false') {
+      ignoredModules.push(
+        '@electron/internal/browser/api/views/image-view.js'
+      );
+    }
+
+    const plugins = [];
+
+    if (onlyPrintingGraph) {
+      plugins.push(new AccessDependenciesPlugin());
+    }
+
+    if (targetDeletesNodeGlobals) {
+      plugins.push(new webpack.ProvidePlugin({
+        process: ['@electron/internal/common/webpack-provider', 'process'],
+        global: ['@electron/internal/common/webpack-provider', '_global'],
+        Buffer: ['@electron/internal/common/webpack-provider', 'Buffer']
+      }));
+    }
+
+    plugins.push(new webpack.ProvidePlugin({
+      Promise: ['@electron/internal/common/webpack-globals-provider', 'Promise']
+    }));
+
+    plugins.push(new webpack.DefinePlugin(defines));
+
+    if (wrapInitWithProfilingTimeout) {
+      plugins.push(new WrapperPlugin({
+        header: 'function ___electron_webpack_init__() {',
+        footer: `
+};
+if ((globalThis.process || binding.process).argv.includes("--profile-electron-init")) {
+  setTimeout(___electron_webpack_init__, 0);
+} else {
+  ___electron_webpack_init__();
+}`
+      }));
+    }
+
+    if (wrapInitWithTryCatch) {
+      plugins.push(new WrapperPlugin({
+        header: 'try {',
+        footer: `
+} catch (err) {
+  console.error('Electron ${outputFilename} script failed to run');
+  console.error(err);
+}`
+      }));
+    }
+
+    return {
+      mode: 'development',
+      devtool: false,
+      entry,
+      target: alwaysHasNode ? 'node' : 'web',
+      output: {
+        filename: outputFilename
+      },
+      resolve: {
+        alias: {
+          '@electron/internal': path.resolve(electronRoot, 'lib'),
+          electron$: electronAPIFile,
+          'electron/main$': electronAPIFile,
+          'electron/renderer$': electronAPIFile,
+          'electron/common$': electronAPIFile,
+          // Force timers to resolve to our dependency that doesn't use window.postMessage
+          timers: path.resolve(electronRoot, 'node_modules', 'timers-browserify', 'main.js')
+        },
+        extensions: ['.ts', '.js']
+      },
+      module: {
+        rules: [{
+          test: (moduleName) => !onlyPrintingGraph && ignoredModules.includes(moduleName),
+          loader: 'null-loader'
+        }, {
+          test: /\.ts$/,
+          loader: 'ts-loader',
+          options: {
+            configFile: path.resolve(electronRoot, 'tsconfig.electron.json'),
+            transpileOnly: onlyPrintingGraph,
+            ignoreDiagnostics: [
+              // File '{0}' is not under 'rootDir' '{1}'.
+              6059
+            ]
+          }
+        }]
+      },
+      node: {
+        __dirname: false,
+        __filename: false,
+        // We provide our own "timers" import above, any usage of setImmediate inside
+        // one of our renderer bundles should import it from the 'timers' package
+        setImmediate: false
+      },
+      optimization: {
+        minimize: true,
+        minimizer: [
+          new TerserPlugin({
+            terserOptions: {
+              keep_classnames: true,
+              keep_fnames: true
+            }
+          })
+        ]
+      },
+      plugins
+    };
+  };
 };

build/webpack/webpack.gni

@@ -16,7 +16,6 @@ template("webpack_build") {
     inputs = [
                invoker.config_file,
                "//electron/build/webpack/webpack.config.base.js",
-               "//electron/build/webpack/run-compiler.js",
                "//electron/tsconfig.json",
                "//electron/yarn.lock",
                "//electron/typings/internal-ambient.d.ts",
@@ -24,9 +23,12 @@ template("webpack_build") {
              ] + invoker.inputs
 
     args = [
+      "--config",
       rebase_path(invoker.config_file),
-      rebase_path(invoker.out_file),
-      "--buildflags=" + rebase_path("$target_gen_dir/buildflags/buildflags.h"),
+      "--output-filename=" + get_path_info(invoker.out_file, "file"),
+      "--output-path=" + rebase_path(get_path_info(invoker.out_file, "dir")),
+      "--env.buildflags=" +
+          rebase_path("$target_gen_dir/buildflags/buildflags.h"),
     ]
     deps += [ "buildflags" ]
 

build/zip.py

@@ -9,31 +9,36 @@ EXTENSIONS_TO_SKIP = [
   '.pdb',
   '.mojom.js',
   '.mojom-lite.js',
-  '.info'
+  '.info',
+  '.m.js'
 ]
 
 PATHS_TO_SKIP = [
-  'angledata', #Skipping because it is an output of //ui/gl that we don't need
-  './libVkICD_mock_', #Skipping because these are outputs that we don't need
-  './VkICD_mock_', #Skipping because these are outputs that we don't need
-
-  # Skipping because its an output of create_bundle from //build/config/mac/rules.gni
-  # that we don't need
+  # Skip because it is an output of //ui/gl that we don't need.
+  'angledata',
+  # Skip because these are outputs that we don't need.
+  './libVkICD_mock_',
+  # Skip because these are outputs that we don't need.
+  './VkICD_mock_',
+  # Skip because its an output of create_bundle from
+  # //build/config/mac/rules.gni that we don't need
   'Electron.dSYM',
-
+  # Refs https://chromium-review.googlesource.com/c/angle/angle/+/2425197.
+  # Remove this when Angle themselves remove the file:
+  # https://issuetracker.google.com/issues/168736059
+  'gen/angle/angle_commit.h',
   # //chrome/browser:resources depends on this via
   # //chrome/browser/resources/ssl/ssl_error_assistant, but we don't need to
   # ship it.
   'pyproto',
-
   # On Windows, this binary doesn't exist (the crashpad handler is built-in).
   # On MacOS, the binary is called 'chrome_crashpad_handler' and is inside the
   # app bundle.
   # On Linux, we don't use crashpad, but this binary is still built for some
   # reason. Exclude it from the zip.
   './crashpad_handler',
-
-  'resources/inspector', #Skipping because these are outputs that we don't need
+  # Skip because these are outputs that we don't need.
+  'resources/inspector',
 ]
 
 def skip_path(dep, dist_zip, target_cpu):
@@ -46,7 +51,12 @@ def skip_path(dep, dist_zip, target_cpu):
   should_skip = (
     any(dep.startswith(path) for path in PATHS_TO_SKIP) or
     any(dep.endswith(ext) for ext in EXTENSIONS_TO_SKIP) or
-    ('arm' in target_cpu and dist_zip == 'mksnapshot.zip' and dep == 'snapshot_blob.bin'))
+    (
+      "arm" in target_cpu
+      and dist_zip == "mksnapshot.zip"
+      and dep == "snapshot_blob.bin"
+    )
+  )
   if should_skip:
     print("Skipping {}".format(dep))
   return should_skip
@@ -60,7 +70,7 @@ def execute(argv):
     raise e
 
 def main(argv):
-  dist_zip, runtime_deps, target_cpu, target_os, flatten_val = argv
+  dist_zip, runtime_deps, target_cpu, _, flatten_val = argv
   should_flatten = flatten_val == "true"
   dist_files = set()
   with open(runtime_deps) as f:
@@ -71,17 +81,28 @@ def main(argv):
   if sys.platform == 'darwin' and not should_flatten:
     execute(['zip', '-r', '-y', dist_zip] + list(dist_files))
   else:
-    with zipfile.ZipFile(dist_zip, 'w', zipfile.ZIP_DEFLATED, allowZip64=True) as z:
+    with zipfile.ZipFile(
+      dist_zip, 'w', zipfile.ZIP_DEFLATED, allowZip64=True
+    ) as z:
       for dep in dist_files:
         if os.path.isdir(dep):
-          for root, dirs, files in os.walk(dep):
-            for file in files:
-              z.write(os.path.join(root, file))
+          for root, _, files in os.walk(dep):
+            for filename in files:
+              z.write(os.path.join(root, filename))
         else:
           basename = os.path.basename(dep)
           dirname = os.path.dirname(dep)
-          arcname = os.path.join(dirname, 'chrome-sandbox') if basename == 'chrome_sandbox' else dep
-          z.write(dep, os.path.basename(arcname) if should_flatten else arcname)
+          arcname = (
+            os.path.join(dirname, 'chrome-sandbox')
+            if basename == 'chrome_sandbox'
+            else dep
+          )
+          z.write(
+            dep,
+            os.path.basename(arcname)
+            if should_flatten
+            else arcname,
+          )
 
 if __name__ == '__main__':
   sys.exit(main(sys.argv[1:]))

buildflags/BUILD.gn

@@ -14,13 +14,13 @@ buildflag_header("buildflags") {
     "ENABLE_OSR=$enable_osr",
     "ENABLE_REMOTE_MODULE=$enable_remote_module",
     "ENABLE_VIEWS_API=$enable_views_api",
-    "ENABLE_PEPPER_FLASH=$enable_pepper_flash",
     "ENABLE_PDF_VIEWER=$enable_pdf_viewer",
     "ENABLE_TTS=$enable_tts",
     "ENABLE_COLOR_CHOOSER=$enable_color_chooser",
     "ENABLE_ELECTRON_EXTENSIONS=$enable_electron_extensions",
     "ENABLE_BUILTIN_SPELLCHECKER=$enable_builtin_spellchecker",
     "ENABLE_PICTURE_IN_PICTURE=$enable_picture_in_picture",
+    "ENABLE_WIN_DARK_MODE_WINDOW_UI=$enable_win_dark_mode_window_ui",
     "OVERRIDE_LOCATION_PROVIDER=$enable_fake_location_provider",
   ]
 }

buildflags/buildflags.gni

@@ -28,12 +28,12 @@ declare_args() {
   # Should not be enabled for release build.
   enable_fake_location_provider = !is_official_build
 
-  # Enable flash plugin support.
-  enable_pepper_flash = true
-
   # Enable Chrome extensions support.
   enable_electron_extensions = true
 
   # Enable Spellchecker support
   enable_builtin_spellchecker = true
+
+  # Undocumented Windows dark mode API
+  enable_win_dark_mode_window_ui = false
 }

chromium_src/BUILD.gn

@@ -26,18 +26,10 @@ static_library("chrome") {
     "//chrome/browser/devtools/devtools_file_system_indexer.h",
     "//chrome/browser/extensions/global_shortcut_listener.cc",
     "//chrome/browser/extensions/global_shortcut_listener.h",
-    "//chrome/browser/extensions/global_shortcut_listener_mac.h",
-    "//chrome/browser/extensions/global_shortcut_listener_mac.mm",
-    "//chrome/browser/extensions/global_shortcut_listener_win.cc",
-    "//chrome/browser/extensions/global_shortcut_listener_win.h",
     "//chrome/browser/icon_loader.cc",
     "//chrome/browser/icon_loader.h",
-    "//chrome/browser/icon_loader_mac.mm",
-    "//chrome/browser/icon_loader_win.cc",
     "//chrome/browser/icon_manager.cc",
     "//chrome/browser/icon_manager.h",
-    "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.h",
-    "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.mm",
     "//chrome/browser/net/chrome_mojo_proxy_resolver_factory.cc",
     "//chrome/browser/net/chrome_mojo_proxy_resolver_factory.h",
     "//chrome/browser/net/proxy_config_monitor.cc",
@@ -57,14 +49,32 @@ static_library("chrome") {
     "//chrome/browser/ssl/tls_deprecation_config.cc",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.cc",
     "//chrome/browser/ui/views/autofill/autofill_popup_view_utils.h",
-    "//chrome/browser/win/chrome_process_finder.cc",
-    "//chrome/browser/win/chrome_process_finder.h",
-    "//chrome/child/v8_crashpad_support_win.cc",
-    "//chrome/child/v8_crashpad_support_win.h",
     "//extensions/browser/app_window/size_constraints.cc",
     "//extensions/browser/app_window/size_constraints.h",
   ]
 
+  if (is_mac) {
+    sources += [
+      "//chrome/browser/extensions/global_shortcut_listener_mac.h",
+      "//chrome/browser/extensions/global_shortcut_listener_mac.mm",
+      "//chrome/browser/icon_loader_mac.mm",
+      "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.h",
+      "//chrome/browser/media/webrtc/system_media_capture_permissions_mac.mm",
+    ]
+  }
+
+  if (is_win) {
+    sources += [
+      "//chrome/browser/extensions/global_shortcut_listener_win.cc",
+      "//chrome/browser/extensions/global_shortcut_listener_win.h",
+      "//chrome/browser/icon_loader_win.cc",
+      "//chrome/browser/win/chrome_process_finder.cc",
+      "//chrome/browser/win/chrome_process_finder.h",
+      "//chrome/child/v8_crashpad_support_win.cc",
+      "//chrome/child/v8_crashpad_support_win.h",
+    ]
+  }
+
   public_deps = [
     "//chrome/common",
     "//chrome/common:version_header",
@@ -83,9 +93,18 @@ static_library("chrome") {
 
   if (is_linux) {
     sources += [ "//chrome/browser/icon_loader_auralinux.cc" ]
+    if (use_x11) {
+      sources += [
+        "//chrome/browser/extensions/global_shortcut_listener_x11.cc",
+        "//chrome/browser/extensions/global_shortcut_listener_x11.h",
+      ]
+    } else if (use_ozone) {
+      sources += [
+        "//chrome/browser/extensions/global_shortcut_listener_ozone.cc",
+        "//chrome/browser/extensions/global_shortcut_listener_ozone.h",
+      ]
+    }
     sources += [
-      "//chrome/browser/extensions/global_shortcut_listener_x11.cc",
-      "//chrome/browser/extensions/global_shortcut_listener_x11.h",
       "//chrome/browser/ui/views/status_icons/concat_menu_model.cc",
       "//chrome/browser/ui/views/status_icons/concat_menu_model.h",
       "//chrome/browser/ui/views/status_icons/status_icon_linux_dbus.cc",
@@ -286,8 +305,6 @@ source_set("plugins") {
   sources += [
     "//chrome/browser/renderer_host/pepper/chrome_browser_pepper_host_factory.cc",
     "//chrome/browser/renderer_host/pepper/chrome_browser_pepper_host_factory.h",
-    "//chrome/browser/renderer_host/pepper/pepper_broker_message_filter.cc",
-    "//chrome/browser/renderer_host/pepper/pepper_broker_message_filter.h",
     "//chrome/browser/renderer_host/pepper/pepper_isolated_file_system_message_filter.cc",
     "//chrome/browser/renderer_host/pepper/pepper_isolated_file_system_message_filter.h",
   ]
@@ -300,26 +317,6 @@ source_set("plugins") {
   if (enable_pdf_viewer) {
     deps += [ "//components/pdf/browser" ]
   }
-  if (enable_pepper_flash) {
-    sources += [
-      "//chrome/browser/renderer_host/pepper/pepper_flash_browser_host.cc",
-      "//chrome/browser/renderer_host/pepper/pepper_flash_browser_host.h",
-      "//chrome/browser/renderer_host/pepper/pepper_flash_clipboard_message_filter.cc",
-      "//chrome/browser/renderer_host/pepper/pepper_flash_clipboard_message_filter.h",
-      "//chrome/browser/renderer_host/pepper/pepper_flash_drm_host.cc",
-      "//chrome/browser/renderer_host/pepper/pepper_flash_drm_host.h",
-    ]
-    if (is_mac) {
-      sources += [
-        "//chrome/browser/renderer_host/pepper/monitor_finder_mac.h",
-        "//chrome/browser/renderer_host/pepper/monitor_finder_mac.mm",
-      ]
-      frameworks += [ "CoreGraphics.framework" ]
-    }
-    if (is_linux) {
-      deps += [ "//components/services/font/public/cpp" ]
-    }
-  }
 
   # renderer side
   sources += [
@@ -328,19 +325,7 @@ source_set("plugins") {
     "//chrome/renderer/pepper/pepper_shared_memory_message_filter.cc",
     "//chrome/renderer/pepper/pepper_shared_memory_message_filter.h",
   ]
-  if (enable_pepper_flash) {
-    sources += [
-      "//chrome/renderer/pepper/pepper_flash_drm_renderer_host.cc",
-      "//chrome/renderer/pepper/pepper_flash_drm_renderer_host.h",
-      "//chrome/renderer/pepper/pepper_flash_fullscreen_host.cc",
-      "//chrome/renderer/pepper/pepper_flash_fullscreen_host.h",
-      "//chrome/renderer/pepper/pepper_flash_menu_host.cc",
-      "//chrome/renderer/pepper/pepper_flash_menu_host.h",
-      "//chrome/renderer/pepper/pepper_flash_renderer_host.cc",
-      "//chrome/renderer/pepper/pepper_flash_renderer_host.h",
-    ]
-  }
-  if (enable_pepper_flash || enable_pdf_viewer) {
+  if (enable_pdf_viewer) {
     sources += [
       "//chrome/renderer/pepper/pepper_flash_font_file_host.cc",
       "//chrome/renderer/pepper/pepper_flash_font_file_host.h",
@@ -367,6 +352,7 @@ source_set("chrome_spellchecker") {
   sources = []
   deps = []
   libs = []
+  public_deps = []
 
   if (enable_builtin_spellchecker) {
     sources += [
@@ -384,7 +370,6 @@ source_set("chrome_spellchecker") {
       "//chrome/browser/spellchecker/spellcheck_language_policy_handler.h",
       "//chrome/browser/spellchecker/spellcheck_service.cc",
       "//chrome/browser/spellchecker/spellcheck_service.h",
-      "//chrome/common/pref_names.h",
     ]
 
     if (has_spellcheck_panel) {
@@ -407,9 +392,11 @@ source_set("chrome_spellchecker") {
       "//components/spellcheck:buildflags",
       "//components/sync",
     ]
+
+    public_deps += [ "//chrome/common:constants" ]
   }
 
-  public_deps = [
+  public_deps += [
     "//components/spellcheck/browser",
     "//components/spellcheck/common",
     "//components/spellcheck/renderer",

chromium_src/chrome/browser/process_singleton_posix.cc

@@ -826,10 +826,9 @@ ProcessSingleton::NotifyResult ProcessSingleton::NotifyOtherProcessWithTimeout(
   to_send.append(current_dir.value());
 
   const std::vector<std::string>& argv = electron::ElectronCommandLine::argv();
-  for (std::vector<std::string>::const_iterator it = argv.begin();
-       it != argv.end(); ++it) {
+  for (const auto& arg : argv) {
     to_send.push_back(kTokenDelimiter);
-    to_send.append(*it);
+    to_send.append(arg);
   }
 
   // Send the message

chromium_src/chrome/browser/ui/views/frame/global_menu_bar_registrar_x11.cc

@@ -122,8 +122,7 @@ void GlobalMenuBarRegistrarX11::OnNameOwnerChanged(GObject* /* ignored */,
                                                    GParamSpec* /* ignored */) {
   // If the name owner changed, we need to reregister all the live x11::Window
   // with the system.
-  for (std::set<x11::Window>::const_iterator it = live_windows_.begin();
-       it != live_windows_.end(); ++it) {
-    RegisterXWindow(*it);
+  for (const auto& window : live_windows_) {
+    RegisterXWindow(window);
   }
 }

docs/README.md

@@ -23,20 +23,20 @@ an issue:
   * [Setting up Windows](tutorial/development-environment.md#setting-up-windows)
   * [Setting up Linux](tutorial/development-environment.md#setting-up-linux)
   * [Choosing an Editor](tutorial/development-environment.md#a-good-editor)
-* [Creating your First App](tutorial/first-app.md)
-  * [Installing Electron](tutorial/first-app.md#installing-electron)
-  * [Electron Development in a Nutshell](tutorial/first-app.md#electron-development-in-a-nutshell)
-  * [Running Your App](tutorial/first-app.md#running-your-app)
+* [Creating your First App](tutorial/quick-start.md)
+  * [Prerequisites](tutorial/quick-start.md#prerequisites)
+  * [Create a basic application](tutorial/quick-start.md#create-a-basic-application)
+  * [Package and distribute the application](tutorial/quick-start.md#package-and-distribute-the-application)
 * [Boilerplates and CLIs](tutorial/boilerplates-and-clis.md)
   * [Boilerplate vs CLI](tutorial/boilerplates-and-clis.md#boilerplate-vs-cli)
   * [electron-forge](tutorial/boilerplates-and-clis.md#electron-forge)
   * [electron-builder](tutorial/boilerplates-and-clis.md#electron-builder)
   * [electron-react-boilerplate](tutorial/boilerplates-and-clis.md#electron-react-boilerplate)
   * [Other Tools and Boilerplates](tutorial/boilerplates-and-clis.md#other-tools-and-boilerplates)
-* [Application Architecture](tutorial/application-architecture.md)
-  * [Main and Renderer Processes](tutorial/application-architecture.md#main-and-renderer-processes)
-  * [Using Electron's APIs](tutorial/application-architecture.md#using-electron-apis)
-  * [Using Node.js APIs](tutorial/application-architecture.md#using-nodejs-apis)
+* [Application Architecture](tutorial/quick-start.md#application-architecture)
+  * [Main and Renderer Processes](tutorial/quick-start.md#main-and-renderer-processes)
+  * [Electron API](tutorial/quick-start.md#electron-api)
+  * [Node.js API](tutorial/quick-start.md#nodejs-api)
   * [Using Native Node.js Modules](tutorial/using-native-node-modules.md)
   * [Performance Strategies](tutorial/performance.md)
 * Adding Features to Your App
@@ -51,7 +51,7 @@ an issue:
   * [Represented File for macOS BrowserWindows](tutorial/represented-file.md)
   * [Native File Drag & Drop](tutorial/native-file-drag-drop.md)
   * [Offscreen Rendering](tutorial/offscreen-rendering.md)
-  * [Supporting macOS Dark Mode](tutorial/mojave-dark-mode-guide.md)
+  * [Dark Mode](tutorial/dark-mode.md)
   * [Web embeds in Electron](tutorial/web-embeds.md)
 * [Accessibility](tutorial/accessibility.md)
   * [Spectron](tutorial/accessibility.md#spectron)
@@ -98,7 +98,6 @@ These individual tutorials expand on topics discussed in the guide above.
   * [Limitations](tutorial/application-packaging.md#limitations-of-the-node-api)
   * [Adding Unpacked Files to asar Archives](tutorial/application-packaging.md#adding-unpacked-files-to-asar-archives)
 * [Testing Widevine CDM](tutorial/testing-widevine-cdm.md)
-* [Using Pepper Flash Plugin](tutorial/using-pepper-flash-plugin.md)
 
 ---
 
@@ -135,6 +134,7 @@ These individual tutorials expand on topics discussed in the guide above.
 * [MenuItem](api/menu-item.md)
 * [net](api/net.md)
 * [netLog](api/net-log.md)
+* [nativeTheme](api/native-theme.md)
 * [Notification](api/notification.md)
 * [powerMonitor](api/power-monitor.md)
 * [powerSaveBlocker](api/power-save-blocker.md)

docs/api/app.md

@@ -32,10 +32,12 @@ In most cases, you should do everything in the `ready` event handler.
 
 Returns:
 
-* `launchInfo` unknown _macOS_
+* `event` Event
+* `launchInfo` Record<string, any> | [NotificationResponse](structures/notification-response.md) _macOS_
 
 Emitted once, when Electron has finished initializing. On macOS, `launchInfo`
-holds the `userInfo` of the `NSUserNotification` that was used to open the
+holds the `userInfo` of the `NSUserNotification` or information from
+[`UNNotificationResponse`](structures/notification-response.md) that was used to open the
 application, if it was launched from Notification Center. You can also call
 `app.isReady()` to check if this event has already fired and `app.whenReady()`
 to get a Promise that is fulfilled when Electron is initialized.
@@ -432,7 +434,8 @@ Returns:
     * `integrity-failure` - Windows code integrity checks failed
   * `exitCode` Number - The exit code for the process
       (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).
-  * `name` String (optional) - The name of the process. i.e. for plugins it might be Flash.
+  * `serviceName` String (optional) - The non-localized name of the process.
+  * `name` String (optional) - The name of the process.
     Examples for utility: `Audio Service`, `Content Decryption Module Service`, `Network Service`, `Video Capture`, etc.
 
 Emitted when the child process unexpectedly disappears. This is normally
@@ -679,7 +682,6 @@ Returns `String` - The current application directory.
   * `videos` Directory for a user's videos.
   * `recent` Directory for the user's recent files (Windows only).
   * `logs` Directory for your app's log folder.
-  * `pepperFlashSystemPlugin` Full path to the system version of the Pepper Flash plugin.
   * `crashDumps` Directory where crash dumps are stored.
 
 Returns `String` - A path to a special directory or file associated with `name`. On
@@ -1103,7 +1105,7 @@ Activation policy types:
 
 Imports the certificate in pkcs12 format into the platform certificate store.
 `callback` is called with the `result` of import operation, a value of `0`
-indicates success while any other value indicates failure according to Chromium [net_error_list](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
+indicates success while any other value indicates failure according to Chromium [net_error_list](https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h).
 
 ### `app.disableHardwareAcceleration()`
 

docs/api/browser-window.md

@@ -398,6 +398,11 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
       * `bypassHeatCheck` - Bypass code caching heuristics but with lazy compilation
       * `bypassHeatCheckAndEagerCompile` - Same as above except compilation is eager.
       Default policy is `code`.
+    * `enablePreferredSizeMode` Boolean (optional) - Whether to enable
+      preferred size mode. The preferred size is the minimum size needed to
+      contain the layout of the document—without requiring scrolling. Enabling
+      this will cause the `preferred-size-changed` event to be emitted on the
+      `WebContents` when the preferred size changes. Default is `false`.
 
 When setting minimum or maximum window size with `minWidth`/`maxWidth`/
 `minHeight`/`maxHeight`, it only constrains the users. It won't prevent you from
@@ -1452,7 +1457,7 @@ Captures a snapshot of the page within `rect`. Omitting `rect` will capture the
   * `httpReferrer` (String | [Referrer](structures/referrer.md)) (optional) - An HTTP Referrer URL.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n"
-  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadBlob[]](structures/upload-blob.md)) (optional)
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md)) (optional)
   * `baseURLForDataURL` String (optional) - Base URL (with trailing path separator) for files to be loaded by the data URL. This is needed only if the specified `url` is a data URL and needs to load other files.
 
 Returns `Promise<void>` - the promise will resolve when the page has finished loading
@@ -1734,7 +1739,9 @@ events.
 Prevents the window contents from being captured by other apps.
 
 On macOS it sets the NSWindow's sharingType to NSWindowSharingNone.
-On Windows it calls SetWindowDisplayAffinity with `WDA_MONITOR`.
+On Windows it calls SetWindowDisplayAffinity with `WDA_EXCLUDEFROMCAPTURE`.
+For Windows 10 version 2004 and up the window will be removed from capture entirely,
+older Windows versions behave as if `WDA_MONITOR` is applied capturing a black window.
 
 #### `win.setFocusable(focusable)` _macOS_ _Windows_
 

docs/api/command-line-switches.md

@@ -171,14 +171,6 @@ authentication [per Chromium issue](https://bugs.chromium.org/p/chromium/issues/
 
 Enables remote debugging over HTTP on the specified `port`.
 
-### --ppapi-flash-path=`path`
-
-Sets the `path` of the pepper flash plugin.
-
-### --ppapi-flash-version=`version`
-
-Sets the `version` of the pepper flash plugin.
-
 ### --v=`log_level`
 
 Gives the default maximal active V-logging level; 0 is the default. Normally
@@ -240,7 +232,7 @@ Specify ways of the inspector web socket url exposure.
 By default inspector websocket url is available in stderr and under /json/list endpoint on http://host:port/json/list.
 
 [app]: app.md
-[append-switch]: app.md#appcommandlineappendswitchswitch-value
+[append-switch]: command-line.md#commandlineappendswitchswitch-value
 [ready]: app.md#event-ready
 [play-silent-audio]: https://github.com/atom/atom/pull/9485/files
 [debugging-main-process]: ../tutorial/debugging-main-process.md

docs/api/desktop-capturer.md

@@ -95,7 +95,7 @@ Returns `Promise<DesktopCapturerSource[]>` - Resolves with an array of [`Desktop
 which can detected by [`systemPreferences.getMediaAccessStatus`].
 
 [`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia
-[`systemPreferences.getMediaAccessStatus`]: system-preferences.md#systempreferencesgetmediaaccessstatusmediatype-macos
+[`systemPreferences.getMediaAccessStatus`]: system-preferences.md#systempreferencesgetmediaaccessstatusmediatype-windows-macos
 
 ## Caveats
 

docs/api/dialog.md

@@ -221,6 +221,7 @@ expanding and collapsing the dialog.
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
+  * `message` String - Content of the message box.
   * `type` String (optional) - Can be `"none"`, `"info"`, `"error"`, `"question"` or
   `"warning"`. On Windows, `"question"` displays the same icon as `"info"`, unless
   you set an icon using the `"icon"` option. On macOS, both `"warning"` and
@@ -230,7 +231,6 @@ expanding and collapsing the dialog.
   * `defaultId` Integer (optional) - Index of the button in the buttons array which will
     be selected by default when the message box opens.
   * `title` String (optional) - Title of the message box, some platforms will not show it.
-  * `message` String - Content of the message box.
   * `detail` String (optional) - Extra information of the message.
   * `checkboxLabel` String (optional) - If provided, the message box will
     include a checkbox with the given label.
@@ -267,6 +267,7 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case
 
 * `browserWindow` [BrowserWindow](browser-window.md) (optional)
 * `options` Object
+  * `message` String - Content of the message box.
   * `type` String (optional) - Can be `"none"`, `"info"`, `"error"`, `"question"` or
   `"warning"`. On Windows, `"question"` displays the same icon as `"info"`, unless
   you set an icon using the `"icon"` option. On macOS, both `"warning"` and
@@ -276,7 +277,6 @@ If `browserWindow` is not shown dialog will not be attached to it. In such case
   * `defaultId` Integer (optional) - Index of the button in the buttons array which will
     be selected by default when the message box opens.
   * `title` String (optional) - Title of the message box, some platforms will not show it.
-  * `message` String - Content of the message box.
   * `detail` String (optional) - Extra information of the message.
   * `checkboxLabel` String (optional) - If provided, the message box will
     include a checkbox with the given label.

docs/api/frameless-window.md

@@ -88,7 +88,7 @@ win.show()
 * On Linux, users have to put `--enable-transparent-visuals --disable-gpu` in
   the command line to disable GPU and allow ARGB to make transparent window,
   this is caused by an upstream bug that [alpha channel doesn't work on some
-  NVidia drivers](https://code.google.com/p/chromium/issues/detail?id=369209) on
+  NVidia drivers](https://bugs.chromium.org/p/chromium/issues/detail?id=369209) on
   Linux.
 * On Mac, the native window shadow will not be shown on a transparent window.
 

docs/api/menu-item.md

@@ -14,7 +14,7 @@ See [`Menu`](menu.md) for examples.
     * `menuItem` MenuItem
     * `browserWindow` [BrowserWindow](browser-window.md) | undefined - This will not be defined if no window is open.
     * `event` [KeyboardEvent](structures/keyboard-event.md)
-  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
+  * `role` String (optional) - Can be `undo`, `redo`, `cut`, `copy`, `paste`, `pasteAndMatchStyle`, `delete`, `selectAll`, `reload`, `forceReload`, `toggleDevTools`, `resetZoom`, `zoomIn`, `zoomOut`, `togglefullscreen`, `window`, `minimize`, `close`, `help`, `about`, `services`, `hide`, `hideOthers`, `unhide`, `quit`, `startSpeaking`, `stopSpeaking`, `zoom`, `front`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `shareMenu`, `recentDocuments`, `toggleTabBar`, `selectNextTab`, `selectPreviousTab`, `mergeAllWindows`, `clearRecentDocuments`, `moveTabToNewWindow` or `windowMenu` - Define the action of the menu item, when specified the
     `click` property will be ignored. See [roles](#roles).
   * `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
@@ -31,6 +31,7 @@ See [`Menu`](menu.md) for examples.
     menu items.
   * `registerAccelerator` Boolean (optional) _Linux_ _Windows_ - If false, the accelerator won't be registered
     with the system, but it will still be displayed. Defaults to true.
+  * `sharingItem` SharingItem (optional) _macOS_ - The item to share when the `role` is `shareMenu`.
   * `submenu` (MenuItemConstructorOptions[] | [Menu](menu.md)) (optional) - Should be specified
     for `submenu` type menu items. If `submenu` is specified, the `type: 'submenu'` can be omitted.
     If the value is not a [`Menu`](menu.md) then it will be automatically converted to one using
@@ -112,6 +113,7 @@ The following additional roles are available on _macOS_:
 * `services` - The submenu is a ["Services"](https://developer.apple.com/documentation/appkit/nsapplication/1428608-servicesmenu?language=objc) menu. This is only intended for use in the Application Menu and is *not* the same as the "Services" submenu used in context menus in macOS apps, which is not implemented in Electron.
 * `recentDocuments` - The submenu is an "Open Recent" menu.
 * `clearRecentDocuments` - Map to the `clearRecentDocuments` action.
+* `shareMenu` - The submenu is [share menu][ShareMenu]. The `sharingItem` property must also be set to indicate the item to share.
 
 When specifying a `role` on macOS, `label` and `accelerator` are the only
 options that will affect the menu item. All other options will be ignored.
@@ -200,6 +202,12 @@ system or just displayed.
 
 This property can be dynamically changed.
 
+#### `menuItem.sharingItem` _macOS_
+
+A `SharingItem` indicating the item to share when the `role` is `shareMenu`.
+
+This property can be dynamically changed.
+
 #### `menuItem.commandId`
 
 A `Number` indicating an item's sequential unique id.
@@ -207,3 +215,5 @@ A `Number` indicating an item's sequential unique id.
 #### `menuItem.menu`
 
 A `Menu` that the item is a part of.
+
+[ShareMenu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

docs/api/net.md

@@ -8,7 +8,7 @@ The `net` module is a client-side API for issuing HTTP(S) requests. It is
 similar to the [HTTP](https://nodejs.org/api/http.html) and
 [HTTPS](https://nodejs.org/api/https.html) modules of Node.js but uses
 Chromium's native networking library instead of the Node.js implementation,
-offering better support for web proxies.
+offering better support for web proxies. It also supports checking network status.
 
 The following is a non-exhaustive list of why you may consider using the `net`
 module instead of the native Node.js modules:
@@ -62,3 +62,25 @@ Creates a [`ClientRequest`](./client-request.md) instance using the provided
 `options` which are directly forwarded to the `ClientRequest` constructor.
 The `net.request` method would be used to issue both secure and insecure HTTP
 requests according to the specified protocol scheme in the `options` object.
+
+### `net.isOnline()`
+
+Returns `Boolean` - Whether there is currently internet connection.
+
+A return value of `false` is a pretty strong indicator that the user
+won't be able to connect to remote sites. However, a return value of
+`true` is inconclusive; even if some link is up, it is uncertain
+whether a particular connection attempt to a particular remote site
+will be successful.
+
+## Properties
+
+### `net.online` _Readonly_
+
+A `Boolean` property. Whether there is currently internet connection.
+
+A return value of `false` is a pretty strong indicator that the user
+won't be able to connect to remote sites. However, a return value of
+`true` is inconclusive; even if some link is up, it is uncertain
+whether a particular connection attempt to a particular remote site
+will be successful.

docs/api/session.md

@@ -283,6 +283,27 @@ Writes any unwritten DOMStorage data to disk.
 #### `ses.setProxy(config)`
 
 * `config` Object
+  * `mode` String (optional) - The proxy mode. Should be one of `direct`,
+    `auto_detect`, `pac_script`, `fixed_servers` or `system`. If it's
+    unspecified, it will be automatically determined based on other specified
+    options.
+    * `direct`
+      In direct mode all connections are created directly, without any proxy involved.
+    * `auto_detect`
+      In auto_detect mode the proxy configuration is determined by a PAC script that can
+      be downloaded at http://wpad/wpad.dat.
+    * `pac_script`
+      In pac_script mode the proxy configuration is determined by a PAC script that is
+      retrieved from the URL specified in the `pacScript`. This is the default mode
+      if `pacScript` is specified.
+    * `fixed_servers`
+      In fixed_servers mode the proxy configuration is specified in `proxyRules`.
+      This is the default mode if `proxyRules` is specified.
+    * `system`
+      In system mode the proxy configuration is taken from the operating system.
+      Note that the system mode is different from setting no proxy configuration.
+      In the latter case, Electron falls back to the system settings
+      only if no command-line options influence the proxy configuration.
   * `pacScript` String (optional) - The URL associated with the PAC file.
   * `proxyRules` String (optional) - Rules indicating which proxies to use.
   * `proxyBypassRules` String (optional) - Rules indicating which URLs should
@@ -292,7 +313,7 @@ Returns `Promise<void>` - Resolves when the proxy setting process is complete.
 
 Sets the proxy settings.
 
-When `pacScript` and `proxyRules` are provided together, the `proxyRules`
+When `mode` is unspecified, `pacScript` and `proxyRules` are provided together, the `proxyRules`
 option is ignored and `pacScript` configuration is applied.
 
 You may need `ses.closeAllConnections` to close currently in flight connections to prevent
@@ -366,6 +387,10 @@ The `proxyBypassRules` is a comma separated list of rules described below:
 
 Returns `Promise<String>` - Resolves with the proxy information for `url`.
 
+#### `ses.forceReloadProxyConfig()`
+
+Returns `Promise<void>` - Resolves when the all internal states of proxy service is reset and the latest proxy configuration is reapplied if it's already available. The pac script will be fetched from `pacScript` again if the proxy mode is `pac_script`.
+
 #### `ses.setDownloadPath(path)`
 
 * `path` String - The download location.
@@ -429,7 +454,7 @@ the original network configuration.
     * `errorCode` Integer - Error code.
   * `callback` Function
     * `verificationResult` Integer - Value can be one of certificate error codes
-    from [here](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h).
+    from [here](https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h).
     Apart from the certificate error codes, the following special codes can be used.
       * `0` - Indicates success and disables Certificate Transparency verification.
       * `-2` - Indicates failure.
@@ -462,6 +487,7 @@ win.webContents.session.setCertificateVerifyProc((request, callback) => {
 * `handler` Function | null
   * `webContents` [WebContents](web-contents.md) - WebContents requesting the permission.  Please note that if the request comes from a subframe you should use `requestingUrl` to check the request origin.
   * `permission` String - The type of requested permission.
+    * `clipboard-read` - Request access to read from the clipboard.
     * `media` -  Request access to media devices such as camera, microphone and speakers.
     * `mediaKeySystem` - Request access to DRM protected content.
     * `geolocation` - Request access to user's current location.
@@ -574,11 +600,20 @@ Returns `String` - The user agent for this session.
 #### `ses.setSSLConfig(config)`
 
 * `config` Object
-  * `minVersion` String - Can be `tls1`, `tls1.1`, `tls1.2` or `tls1.3`. The
+  * `minVersion` String (optional) - Can be `tls1`, `tls1.1`, `tls1.2` or `tls1.3`. The
     minimum SSL version to allow when connecting to remote servers. Defaults to
     `tls1`.
-  * `maxVersion` String - Can be `tls1.2` or `tls1.3`. The maximum SSL version
+  * `maxVersion` String (optional) - Can be `tls1.2` or `tls1.3`. The maximum SSL version
     to allow when connecting to remote servers. Defaults to `tls1.3`.
+  * `disabledCipherSuites` Integer[] (optional) - List of cipher suites which
+    should be explicitly prevented from being used in addition to those
+    disabled by the net built-in policy.
+    Supported literal forms: 0xAABB, where AA is `cipher_suite[0]` and BB is
+    `cipher_suite[1]`, as defined in RFC 2246, Section 7.4.1.2. Unrecognized but
+    parsable cipher suites in this form will not return an error.
+    Ex: To disable TLS_RSA_WITH_RC4_128_MD5, specify 0x0004, while to
+    disable TLS_ECDH_ECDSA_WITH_RC4_128_SHA, specify 0xC002.
+    Note that TLSv1.3 ciphers cannot be disabled using this mechanism.
 
 Sets the SSL configuration for the session. All subsequent network requests
 will use the new configuration. Existing network connections (such as WebSocket
@@ -789,12 +824,12 @@ const path = require('path')
 
 app.whenReady().then(() => {
   const protocol = session.fromPartition('some-partition').protocol
-  protocol.registerFileProtocol('atom', (request, callback) => {
+  if (!protocol.registerFileProtocol('atom', (request, callback) => {
     const url = request.url.substr(7)
     callback({ path: path.normalize(`${__dirname}/${url}`) })
-  }, (error) => {
-    if (error) console.error('Failed to register protocol')
-  })
+  })) {
+    console.error('Failed to register protocol')
+  }
 })
 ```
 

docs/api/share-menu.md

@@ -0,0 +1,45 @@
+## Class: ShareMenu
+
+> Create share menu on macOS.
+
+Process: [Main](../glossary.md#main-process)
+
+The `ShareMenu` class creates [Share Menu][share-menu] on macOS, which can be
+used to share information from the current context to apps, social media
+accounts, and other services.
+
+For including the share menu as a submenu of other menus, please use the
+`shareMenu` role of [`MenuItem`](menu-item.md).
+
+### `new ShareMenu(sharingItem)`
+
+* `sharingItem` SharingItem - The item to share.
+
+Creates a new share menu.
+
+### Instance Methods
+
+The `shareMenu` object has the following instance methods:
+
+#### `shareMenu.popup([options])`
+
+* `options` PopupOptions (optional)
+  * `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
+  * `x` Number (optional) - Default is the current mouse cursor position.
+    Must be declared if `y` is declared.
+  * `y` Number (optional) - Default is the current mouse cursor position.
+    Must be declared if `x` is declared.
+  * `positioningItem` Number (optional) _macOS_ - The index of the menu item to
+    be positioned under the mouse cursor at the specified coordinates. Default
+    is -1.
+  * `callback` Function (optional) - Called when menu is closed.
+
+Pops up this menu as a context menu in the [`BrowserWindow`](browser-window.md).
+
+#### `shareMenu.closePopup([browserWindow])`
+
+* `browserWindow` [BrowserWindow](browser-window.md) (optional) - Default is the focused window.
+
+Closes the context menu in the `browserWindow`.
+
+[share-menu]: https://developer.apple.com/design/human-interface-guidelines/macos/extensions/share-extensions/

docs/api/structures/ipc-renderer-event.md

@@ -4,4 +4,4 @@
 * `senderId` Integer - The `webContents.id` that sent the message, you can call `event.sender.sendTo(event.senderId, ...)` to reply to the message, see [ipcRenderer.sendTo][ipc-renderer-sendto] for more information. This only applies to messages sent from a different renderer. Messages sent directly from the main process set `event.senderId` to `0`.
 * `ports` MessagePort[] - A list of MessagePorts that were transferred with this message
 
-[ipc-renderer-sendto]: #ipcrenderersendtowindowid-channel--arg1-arg2-
+[ipc-renderer-sendto]: ../ipc-renderer.md#ipcrenderersendtowebcontentsid-channel-args

docs/api/structures/notification-response.md

@@ -0,0 +1,7 @@
+# NotificationResponse Object
+
+* `actionIdentifier` String - The identifier string of the action that the user selected.
+* `date` Number - The delivery date of the notification.
+* `identifier` String - The unique identifier for this notification request.
+* `userInfo` Record<String, any> - A dictionary of custom information associated with the notification.
+* `userText` String (optional) - The text entered or chosen by the user.

docs/api/structures/process-metric.md

@@ -11,7 +11,8 @@
   * `Pepper Plugin`
   * `Pepper Plugin Broker`
   * `Unknown`
-* `name` String (optional) - The name of the process. i.e. for plugins it might be Flash.
+* `serviceName` String (optional) - The non-localized name of the process.
+* `name` String (optional) - The name of the process.
     Examples for utility: `Audio Service`, `Content Decryption Module Service`, `Network Service`, `Video Capture`, etc.
 * `cpu` [CPUUsage](cpu-usage.md) - CPU usage of the process.
 * `creationTime` Number - Creation time for this process.

docs/api/structures/protocol-response.md

@@ -28,7 +28,7 @@
 * `session` Session (optional) - The session used for requesting URL, by default
   the HTTP request will reuse the current session. Setting `session` to `null`
   would use a random independent session. This is only used for URL responses.
-* `uploadData` ProtocolResponseUploadData (optional) - The data used as upload data. This is only
+* `uploadData` [ProtocolResponseUploadData](protocol-response-upload-data.md) (optional) - The data used as upload data. This is only
   used for URL responses when `method` is `"POST"`.
 
-[net-error]: https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h
+[net-error]: https://source.chromium.org/chromium/chromium/src/+/master:net/base/net_error_list.h

docs/api/structures/serial-port.md

@@ -1,8 +1,10 @@
 # SerialPort Object
 
-* `portId` String - Unique identifier for the port
-* `portName` String - Name of the port
-* `displayName` String - Addtional information for the port
-* `persistentId` String - This platform-specific identifier, if present, can be used to identify the device across restarts of the application and operating system.
-* `vendorId` String - Optional USB vendor ID
-* `productId` String - Optional USB product ID
+* `portId` String - Unique identifier for the port.
+* `portName` String - Name of the port.
+* `displayName` String - A string suitable for display to the user for describing this device.
+* `vendorId` String - Optional USB vendor ID.
+* `productId` String - Optional USB product ID.
+* `serialNumber` String - The USB device serial number.
+* `usbDriverName` String (optional) - Represents a single serial port on macOS can be enumerated by multiple drivers.
+* `deviceInstanceId` String (optional) - A stable identifier on Windows that can be used for device permissions.

docs/api/structures/sharing-item.md

@@ -0,0 +1,5 @@
+# SharingItem Object
+
+* `texts` String[] (optional) - An array of text to share.
+* `filePaths` String[] (optional) - An array of files to share.
+* `urls` String[] (optional) - An array of URLs to share.

docs/api/structures/upload-blob.md

@@ -1,4 +0,0 @@
-# UploadBlob Object
-
-* `type` String - `blob`.
-* `blobUUID` String - UUID of blob data to upload.

docs/api/synopsis.md

@@ -13,7 +13,7 @@ either process type.
 
 The basic rule is: if a module is [GUI][gui] or low-level system related, then
 it should be only available in the main process. You need to be familiar with
-the concept of [main process vs. renderer process](../tutorial/application-architecture.md#main-and-renderer-processes)
+the concept of [main process vs. renderer process](../tutorial/quick-start.md#main-and-renderer-processes)
 scripts to be able to use those modules.
 
 The main process script is like a normal Node.js script:
@@ -43,7 +43,7 @@ extra ability to use node modules if `nodeIntegration` is enabled:
 </html>
 ```
 
-To run your app, read [Run your app](../tutorial/first-app.md#running-your-app).
+To run your app, read [Run your app](../tutorial/quick-start.md#run-your-application).
 
 ## Destructuring assignment
 

docs/api/system-preferences.md

@@ -51,8 +51,6 @@ Returns:
 
 Returns `Boolean` - Whether the system is in Dark Mode.
 
-**Note:** On macOS 10.15 Catalina in order for this API to return the correct value when in the "automatic" dark mode setting you must either have `NSRequiresAquaSystemAppearance=false` in your `Info.plist` or be on Electron `>=7.0.0`.  See the [dark mode guide](../tutorial/mojave-dark-mode-guide.md) for more information.
-
 **Deprecated:** Should use the new [`nativeTheme.shouldUseDarkColors`](native-theme.md#nativethemeshouldusedarkcolors-readonly) API.
 
 ### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_

docs/api/touch-bar-button.md

@@ -2,7 +2,7 @@
 
 > Create a button in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarButton(options)`
 

docs/api/touch-bar-color-picker.md

@@ -2,7 +2,7 @@
 
 > Create a color picker in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarColorPicker(options)`
 

docs/api/touch-bar-group.md

@@ -2,7 +2,7 @@
 
 > Create a group in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarGroup(options)`
 

docs/api/touch-bar-label.md

@@ -2,7 +2,7 @@
 
 > Create a label in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarLabel(options)`
 

docs/api/touch-bar-other-items-proxy.md

@@ -7,6 +7,6 @@
 >
 > Note: Only one instance of this class can be added per TouchBar.
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarOtherItemsProxy()`

docs/api/touch-bar-popover.md

@@ -2,7 +2,7 @@
 
 > Create a popover in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarPopover(options)`
 

docs/api/touch-bar-scrubber.md

@@ -2,7 +2,7 @@
 
 > Create a scrubber (a scrollable selector)
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarScrubber(options)`
 

docs/api/touch-bar-segmented-control.md

@@ -2,7 +2,7 @@
 
 > Create a segmented control (a button group) where one button has a selected state
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarSegmentedControl(options)`
 

docs/api/touch-bar-slider.md

@@ -2,7 +2,7 @@
 
 > Create a slider in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarSlider(options)`
 

docs/api/touch-bar-spacer.md

@@ -2,7 +2,7 @@
 
 > Create a spacer between two items in the touch bar for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBarSpacer(options)`
 

docs/api/touch-bar.md

@@ -2,7 +2,7 @@
 
 > Create TouchBar layouts for native macOS applications
 
-Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
+Process: [Main](../glossary.md#main-process)
 
 ### `new TouchBar(options)`
 

docs/api/web-contents.md

@@ -837,6 +837,19 @@ Emitted when `remote.getCurrentWebContents()` is called in the renderer process.
 Calling `event.preventDefault()` will prevent the object from being returned.
 Custom value can be returned by setting `event.returnValue`.
 
+#### Event: 'preferred-size-changed'
+
+Returns:
+
+* `event` Event
+* `preferredSize` [Size](structures/size.md) - The minimum size needed to
+  contain the layout of the document—without requiring scrolling.
+
+Emitted when the `WebContents` preferred size has changed.
+
+This event will only be emitted when `enablePreferredSizeMode` is set to `true`
+in `webPreferences`.
+
 ### Instance Methods
 
 #### `contents.loadURL(url[, options])`
@@ -846,7 +859,7 @@ Custom value can be returned by setting `event.returnValue`.
   * `httpReferrer` (String | [Referrer](structures/referrer.md)) (optional) - An HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n".
-  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadBlob[]](structures/upload-blob.md)) (optional)
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md)) (optional)
   * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
 
 Returns `Promise<void>` - the promise will resolve when the page has finished loading

docs/api/web-frame-main.md

@@ -122,9 +122,18 @@ content. The identifier is fixed at the creation of the frame and stays
 constant for the lifetime of the frame. When the frame is removed, the id is
 not used again.
 
+#### `frame.name` _Readonly_
+
+A `String` representing the frame name.
+
+#### `frame.osProcessId` _Readonly_
+
+An `Integer` representing the operating system `pid` of the process which owns this frame.
+
 #### `frame.processId` _Readonly_
 
-An `Integer` representing the id of the process which owns this frame.
+An `Integer` representing the Chromium internal `pid` of the process which owns this frame.
+This is not the same as the OS process ID; to read that use `frame.osProcessId`.
 
 #### `frame.routingId` _Readonly_
 

docs/api/web-frame.md

@@ -257,6 +257,20 @@ renderer process.
 
 Returns `WebFrame` - that has the supplied `routingId`, `null` if not found.
 
+### `webFrame.isWordMisspelled(word)`
+
+* `word` String - The word to be spellchecked.
+
+Returns `Boolean` - True if the word is misspelled according to the built in
+spellchecker, false otherwise. If no dictionary is loaded, always return false.
+
+### `webFrame.getWordSuggestions(word)`
+
+* `word` String - The misspelled word.
+
+Returns `String[]` - A list of suggested words for a given word. If the word
+is spelled correctly, the result will be empty.
+
 ## Properties
 
 ### `webFrame.top` _Readonly_

docs/api/webview-tag.md

@@ -274,7 +274,7 @@ webview.addEventListener('dom-ready', () => {
   * `httpReferrer` (String | [Referrer](structures/referrer.md)) (optional) - An HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.
   * `extraHeaders` String (optional) - Extra headers separated by "\n"
-  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md) | [UploadBlob[]](structures/upload-blob.md)) (optional)
+  * `postData` ([UploadRawData[]](structures/upload-raw-data.md) | [UploadFile[]](structures/upload-file.md)) (optional)
   * `baseURLForDataURL` String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified `url` is a data url and needs to load other files.
 
 Returns `Promise<void>` - The promise will resolve when the page has finished loading

docs/breaking-changes-ns.md

@@ -1,61 +0,0 @@
-# Breaking changes (NetworkService) (Draft)
-
-This document describes changes to Electron APIs after migrating network code
-to NetworkService API.
-
-We don't currently have an estimate of when we will enable `NetworkService` by
-default in Electron, but as Chromium is already removing non-`NetworkService`
-code, we might switch before Electron 10.
-
-The content of this document should be moved to `breaking-changes.md` once we have
-determined when to enable `NetworkService` in Electron.
-
-## Planned Breaking API Changes
-
-### `protocol.unregisterProtocol`
-### `protocol.uninterceptProtocol`
-
-The APIs are now synchronous and the optional callback is no longer needed.
-
-```javascript
-// Deprecated
-protocol.unregisterProtocol(scheme, () => { /* ... */ })
-// Replace with
-protocol.unregisterProtocol(scheme)
-```
-
-### `protocol.registerFileProtocol`
-### `protocol.registerBufferProtocol`
-### `protocol.registerStringProtocol`
-### `protocol.registerHttpProtocol`
-### `protocol.registerStreamProtocol`
-### `protocol.interceptFileProtocol`
-### `protocol.interceptStringProtocol`
-### `protocol.interceptBufferProtocol`
-### `protocol.interceptHttpProtocol`
-### `protocol.interceptStreamProtocol`
-
-The APIs are now synchronous and the optional callback is no longer needed.
-
-```javascript
-// Deprecated
-protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
-// Replace with
-protocol.registerFileProtocol(scheme, handler)
-```
-
-The registered or intercepted protocol does not have effect on current page
-until navigation happens.
-
-### `protocol.isProtocolHandled`
-
-This API is deprecated and users should use `protocol.isProtocolRegistered`
-and `protocol.isProtocolIntercepted` instead.
-
-```javascript
-// Deprecated
-protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
-// Replace with
-const isRegistered = protocol.isProtocolRegistered(scheme)
-const isIntercepted = protocol.isProtocolIntercepted(scheme)
-```

docs/breaking-changes.md

@@ -28,6 +28,12 @@ shell.trashItem(path).then(/* ... */)
 
 ## Planned Breaking API Changes (12.0)
 
+### Removed: Pepper Flash support
+
+Chromium has removed support for Flash, and so we must follow suit. See
+Chromium's [Flash Roadmap](https://www.chromium.org/flash-roadmap) for more
+details.
+
 ### Default Changed: `contextIsolation` defaults to `true`
 
 In Electron 12, `contextIsolation` will be enabled by default.  To restore
@@ -178,6 +184,54 @@ const w = new BrowserWindow({
 We [recommend moving away from the remote
 module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-70d69500f31).
 
+### `protocol.unregisterProtocol`
+### `protocol.uninterceptProtocol`
+
+The APIs are now synchronous and the optional callback is no longer needed.
+
+```javascript
+// Deprecated
+protocol.unregisterProtocol(scheme, () => { /* ... */ })
+// Replace with
+protocol.unregisterProtocol(scheme)
+```
+
+### `protocol.registerFileProtocol`
+### `protocol.registerBufferProtocol`
+### `protocol.registerStringProtocol`
+### `protocol.registerHttpProtocol`
+### `protocol.registerStreamProtocol`
+### `protocol.interceptFileProtocol`
+### `protocol.interceptStringProtocol`
+### `protocol.interceptBufferProtocol`
+### `protocol.interceptHttpProtocol`
+### `protocol.interceptStreamProtocol`
+
+The APIs are now synchronous and the optional callback is no longer needed.
+
+```javascript
+// Deprecated
+protocol.registerFileProtocol(scheme, handler, () => { /* ... */ })
+// Replace with
+protocol.registerFileProtocol(scheme, handler)
+```
+
+The registered or intercepted protocol does not have effect on current page
+until navigation happens.
+
+### `protocol.isProtocolHandled`
+
+This API is deprecated and users should use `protocol.isProtocolRegistered`
+and `protocol.isProtocolIntercepted` instead.
+
+```javascript
+// Deprecated
+protocol.isProtocolHandled(scheme).then(() => { /* ... */ })
+// Replace with
+const isRegistered = protocol.isProtocolRegistered(scheme)
+const isIntercepted = protocol.isProtocolIntercepted(scheme)
+```
+
 ## Planned Breaking API Changes (9.0)
 
 ### Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default

docs/development/README.md

@@ -12,6 +12,7 @@ For guides on Electron app development, see
 * [Source Code Directory Structure](source-code-directory-structure.md)
 * [Coding Style](coding-style.md)
 * [Using clang-format on C++ Code](clang-format.md)
+* [Using clang-tidy on C++ Code](clang-tidy.md)
 * [Build System Overview](build-system-overview.md)
 * [Build Instructions (macOS)](build-instructions-macos.md)
 * [Build Instructions (Windows)](build-instructions-windows.md)

docs/development/build-instructions-gn.md

@@ -26,7 +26,7 @@ Security` → `System` → `Advanced system settings` and add a system variable
 your locally installed version of Visual Studio (by default, `depot_tools` will
 try to download a Google-internal version that only Googlers have access to).
 
-[depot-tools]: http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
+[depot-tools]: https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up
 
 ### Setting up the git cache
 
@@ -254,6 +254,25 @@ New-ItemProperty -Path "HKLM:\System\CurrentControlSet\Services\Lanmanworkstatio
 
 ## Troubleshooting
 
+### gclient sync complains about rebase
+
+If `gclient sync` is interrupted the git tree may be left in a bad state, leading to a cryptic message when running `gclient sync` in the future:
+
+```plaintext
+2> Conflict while rebasing this branch.
+2> Fix the conflict and run gclient again.
+2> See man git-rebase for details.
+```
+
+If there are no git conflicts or rebases in `src/electron`, you may need to abort a `git am` in `src`:
+
+```sh
+$ cd ../
+$ git am --abort
+$ cd electron
+$ gclient sync -f
+```
+
 ### I'm being asked for a username/password for chromium-internal.googlesource.com
 If you see a prompt for `Username for 'https://chrome-internal.googlesource.com':` when running `gclient sync` on Windows, it's probably because the `DEPOT_TOOLS_WIN_TOOLCHAIN` environment variable is not set to 0. Open `Control Panel` → `System and Security` → `System` → `Advanced system settings` and add a system variable
 `DEPOT_TOOLS_WIN_TOOLCHAIN` with value `0`.  This tells `depot_tools` to use

docs/development/build-instructions-windows.md

@@ -13,17 +13,10 @@ Follow the guidelines below for building Electron on Windows.
   set a few environment variables to point the toolchains to your installation path.
     * `vs2019_install = DRIVE:\path\to\Microsoft Visual Studio\2019\Community`, replacing `2019` and `Community` with your installed versions and replacing `DRIVE:` with the drive that Visual Studio is on. Often, this will be `C:`.
     * `WINDOWSSDKDIR = DRIVE:\path\to\Windows Kits\10`, replacing `DRIVE:` with the drive that Windows Kits is on. Often, this will be `C:`.
-* [Python 2.7.10 or higher](http://www.python.org/download/releases/2.7/)
-  * Contrary to the `depot_tools` setup instructions linked below, you will need
-  to use your locally installed Python with at least version 2.7.10 (with
-  support for TLS 1.2). To do so, make sure that in **PATH**, your locally
-  installed Python comes before the `depot_tools` folder. Right now
-  `depot_tools` still comes with Python 2.7.6, which will cause the `gclient`
-  command to fail (see https://crbug.com/868864).
   * [Python for Windows (pywin32) Extensions](https://pypi.org/project/pywin32/#files)
   is also needed in order to run the build process.
 * [Node.js](https://nodejs.org/download/)
-* [Git](http://git-scm.com)
+* [Git](https://git-scm.com)
 * Debugging Tools for Windows of Windows SDK 10.0.15063.468 if you plan on
 creating a full distribution since `symstore.exe` is used for creating a symbol
 store from `.pdb` files.
@@ -50,6 +43,13 @@ building with Visual Studio will come in the future.
 **Note:** Even though Visual Studio is not used for building, it's still
 **required** because we need the build toolchains it provides.
 
+## Exclude source tree from Windows Security
+
+Windows Security doesn't like one of the files in the Chromium source code
+(see https://crbug.com/441184), so it will constantly delete it, causing `gclient sync` issues.
+You can exclude the source tree from being monitored by Windows Security by
+[following these instructions](https://support.microsoft.com/en-us/windows/add-an-exclusion-to-windows-security-811816c0-4dfd-af4a-47e4-c301afe13b26).
+
 ## Building
 
 See [Build Instructions: GN](build-instructions-gn.md)

docs/development/chromium-development.md

@@ -8,6 +8,6 @@
 - [Code Search](https://cs.chromium.org/)
 - [Source Code](https://cs.chromium.org/chromium/src/)
 - [Development Calendar and Release Info](https://www.chromium.org/developers/calendar)
-- [Discussion Groups](http://www.chromium.org/developers/discussion-groups)
+- [Discussion Groups](https://www.chromium.org/developers/discussion-groups)
 
 See also [V8 Development](v8-development.md)

docs/development/clang-format.md

@@ -1,6 +1,6 @@
 # Using clang-format on C++ Code
 
-[`clang-format`](http://clang.llvm.org/docs/ClangFormat.html) is a tool to
+[`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) is a tool to
 automatically format C/C++/Objective-C code, so that developers don't need to
 worry about style issues during code reviews.
 
@@ -31,5 +31,5 @@ You can also integrate `clang-format` directly into your favorite editors.
 For further guidance on setting up editor integration, see these pages:
 
   * [Atom](https://atom.io/packages/clang-format)
-  * [Vim & Emacs](http://clang.llvm.org/docs/ClangFormat.html#vim-integration)
+  * [Vim & Emacs](https://clang.llvm.org/docs/ClangFormat.html#vim-integration)
   * [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)

docs/development/clang-tidy.md

@@ -0,0 +1,37 @@
+# Using clang-tidy on C++ Code
+
+[`clang-tidy`](https://clang.llvm.org/extra/clang-tidy/) is a tool to
+automatically check C/C++/Objective-C code for style violations, programming
+errors, and best practices.
+
+Electron's `clang-tidy` integration is provided as a linter script which can
+be run with `npm run lint:clang-tidy`. While `clang-tidy` checks your on-disk
+files, you need to have built Electron so that it knows which compiler flags
+were used. There is one required option for the script `--output-dir`, which
+tells the script which build directory to pull the compilation information
+from. A typical usage would be:
+`npm run lint:clang-tiy --out-dir ../out/Testing`
+
+With no filenames provided, all C/C++/Objective-C files will be checked.
+You can provide a list of files to be checked by passing the filenames after
+the options:
+`npm run lint:clang-tiy --out-dir ../out/Testing shell/browser/api/electron_api_app.cc`
+
+While `clang-tidy` has a
+[long list](https://clang.llvm.org/extra/clang-tidy/checks/list.html)
+of possible checks, in Electron only a few are enabled by default. At the
+moment Electron doesn't have a `.clang-tidy` config, so `clang-tidy` will
+find the one from Chromium at `src/.clang-tidy` and use the checks which
+Chromium has enabled. You can change which checks are run by using the
+`--checks=` option. This is passed straight through to `clang-tidy`, so see
+its documentation for full details. Wildcards can be used, and checks can
+be disabled by prefixing a `-`. By default any checks listed are added to
+those in `.clang-tidy`, so if you'd like to limit the checks to specific
+ones you should first exclude all checks then add back what you want, like
+`--checks=-*,performance*`.
+
+Running `clang-tidy` is rather slow - internally it compiles each file and
+then runs the checks so it will always be some factor slower than compilation.
+While you can use parallel runs to speed it up using the `--jobs|-j` option,
+`clang-tidy` also uses a lot of memory during its checks, so it can easily
+run into out-of-memory errors. As such the default number of jobs is one.

docs/development/coding-style.md

@@ -47,7 +47,7 @@ formatted correctly.
 
 ## JavaScript
 
-* Write [standard](https://npm.im/standard) JavaScript style.
+* Write [standard](https://www.npmjs.com/package/standard) JavaScript style.
 * File names should be concatenated with `-` instead of `_`, e.g.
   `file-name.js` rather than `file_name.js`, because in
   [github/atom](https://github.com/github/atom) module names are usually in

docs/development/debugging-instructions-macos.md

@@ -129,4 +129,4 @@ will explain more complex debugging scenarios.
 
 [lldb-command-structure]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/gdb_to_lldb_transition_guide/document/lldb-basics.html#//apple_ref/doc/uid/TP40012917-CH2-SW2
 [lldb-standalone]: https://developer.apple.com/library/mac/documentation/IDEs/Conceptual/gdb_to_lldb_transition_guide/document/lldb-terminal-workflow-tutorial.html
-[lldb-tutorial]: http://lldb.llvm.org/tutorial.html
+[lldb-tutorial]: https://lldb.llvm.org/tutorial.html

docs/development/electron-vs-nwjs.md

@@ -19,7 +19,7 @@ application.
 
 Electron works more like the Node.js runtime. Electron's APIs are lower level so
 you can use it for browser testing in place of
-[PhantomJS](http://phantomjs.org/).
+[PhantomJS](https://phantomjs.org/).
 
 ## 2) Node Integration
 

docs/development/v8-development.md

@@ -2,10 +2,10 @@
 
 > A collection of resources for learning and using V8
 
-* [V8 Tracing](https://github.com/v8/v8/wiki/Tracing-V8)
-* [V8 Profiler](https://github.com/v8/v8/wiki/V8-Profiler) - Profiler combinations which are useful for profiling: `--prof`, `--trace-ic`, `--trace-opt`, `--trace-deopt`, `--print-bytecode`, `--print-opt-code`
+* [V8 Tracing](https://v8.dev/docs/trace)
+* [V8 Profiler](https://v8.dev/docs/profile) - Profiler combinations which are useful for profiling: `--prof`, `--trace-ic`, `--trace-opt`, `--trace-deopt`, `--print-bytecode`, `--print-opt-code`
 * [V8 Interpreter Design](https://docs.google.com/document/d/11T2CRex9hXxoJwbYqVQ32yIPMh0uouUZLdyrtmMoL44/edit?ts=56f27d9d#heading=h.6jz9dj3bnr8t)
-* [Optimizing compiler](https://github.com/v8/v8/wiki/TurboFan)
-* [V8 GDB Debugging](https://github.com/v8/v8/wiki/GDB-JIT-Interface)
+* [Optimizing compiler](https://v8.dev/docs/turbofan)
+* [V8 GDB Debugging](https://v8.dev/docs/gdb-jit)
 
 See also [Chromium Development](chromium-development.md)

docs/faq.md

@@ -133,7 +133,7 @@ is only available in renderer processes.
 
 ## The font looks blurry, what is this and what can I do?
 
-If [sub-pixel anti-aliasing](http://alienryderflex.com/sub_pixel/) is deactivated, then fonts on LCD screens can look blurry. Example:
+If [sub-pixel anti-aliasing](https://alienryderflex.com/sub_pixel/) is deactivated, then fonts on LCD screens can look blurry. Example:
 
 ![subpixel rendering example]
 

docs/glossary.md

@@ -159,7 +159,7 @@ building it.
 V8's version numbers always correspond to those of Google Chrome. Chrome 59
 includes V8 5.9, Chrome 58 includes V8 5.8, etc.
 
-- [developers.google.com/v8](https://developers.google.com/v8)
+- [v8.dev](https://v8.dev/)
 - [nodejs.org/api/v8.html](https://nodejs.org/api/v8.html)
 - [docs/development/v8-development.md](development/v8-development.md)
 

docs/styleguide.md

@@ -48,7 +48,7 @@ For API references, there are exceptions to this rule.
 * Lines should be wrapped at 80 columns.
 * No nesting lists more than 2 levels (due to the markdown renderer).
 * All `js` and `javascript` code blocks are linted with
-[standard-markdown](http://npm.im/standard-markdown).
+[standard-markdown](https://www.npmjs.com/package/standard-markdown).
 
 ## Picking words
 

docs/tutorial/application-architecture.md

@@ -1,147 +0,0 @@
-# Electron Application Architecture
-
-Before we can dive into Electron's APIs, we need to discuss the two process
-types available in Electron. They are fundamentally different and important to
-understand.
-
-## Main and Renderer Processes
-
-In Electron, the process that runs `package.json`'s `main` script is called
-__the main process__. The script that runs in the main process can display a
-GUI by creating web pages. An Electron app always has one main process, but
-never more.
-
-Since Electron uses Chromium for displaying web pages, Chromium's
-multi-process architecture is also used. Each web page in Electron runs in
-its own process, which is called __the renderer process__.
-
-In normal browsers, web pages usually run in a sandboxed environment and are not
-allowed access to native resources. Electron users, however, have the power to
-use Node.js APIs in web pages allowing lower level operating system
-interactions.
-
-### Differences Between Main Process and Renderer Process
-
-The main process creates web pages by creating `BrowserWindow` instances. Each
-`BrowserWindow` instance runs the web page in its own renderer process. When a
-`BrowserWindow` instance is destroyed, the corresponding renderer process
-is also terminated.
-
-The main process manages all web pages and their corresponding renderer
-processes. Each renderer process is isolated and only cares about the web page
-running in it.
-
-In web pages, calling native GUI related APIs is not allowed because managing
-native GUI resources in web pages is very dangerous and it is easy to leak
-resources. If you want to perform GUI operations in a web page, the renderer
-process of the web page must communicate with the main process to request that
-the main process perform those operations.
-
-> #### Aside: Communication Between Processes
-> In Electron, communicating between the main process and renderer processes,
-> is done through the [`ipcRenderer`](../api/ipc-renderer.md) and
-> [`ipcMain`](../api/ipc-main.md) modules. There is also an FAQ entry on [how
-> to share data between web pages][share-data].
-
-
-## Using Electron APIs
-
-Electron offers a number of APIs that support the development of a desktop
-application in both the main process and the renderer process. In both
-processes, you'd access Electron's APIs by requiring its included module:
-
-```javascript
-const electron = require('electron')
-```
-
-All Electron APIs are assigned a process type. Many of them can only be
-used from the main process, some of them only from a renderer process,
-some from both. The documentation for each individual API will
-state which process it can be used from.
-
-A window in Electron is for instance created using the `BrowserWindow`
-class. It is only available in the main process.
-
-```javascript
-// This will work in the main process, but be `undefined` in a
-// renderer process:
-const { BrowserWindow } = require('electron')
-
-const win = new BrowserWindow()
-```
-
-Since communication between the processes is possible, a renderer process
-can call upon the main process to perform tasks through IPC.
-
-```javascript
-// In the main process:
-const { ipcMain } = require('electron')
-
-ipcMain.handle('perform-action', (event, ...args) => {
-  // ... do something on behalf of the renderer ...
-})
-
-// In the renderer process:
-const { ipcRenderer } = require('electron')
-
-ipcRenderer.invoke('perform-action', ...args)
-```
-
-Note that code in the renderer may not be trustworthy, so it's important
-to carefully validate in the main process requests that come from renderers,
-especially if they host third-party content.
-
-## Using Node.js APIs
-
-Electron exposes full access to Node.js both in the main and the renderer
-process. This has two important implications:
-
-1) All APIs available in Node.js are available in Electron. Calling the
-following code from an Electron app works:
-
-```javascript
-const fs = require('fs')
-
-const root = fs.readdirSync('/')
-
-// This will print all files at the root-level of the disk,
-// either '/' or 'C:\'.
-console.log(root)
-```
-
-As you might already be able to guess, this has important security implications
-if you ever attempt to load remote content. You can find more information and
-guidance on loading remote content in our [security documentation][security].
-
-2) You can use Node.js modules in your application. Pick your favorite npm
-module. npm offers currently the world's biggest repository of open-source
-code – the ability to use well-maintained and tested code that used to be
-reserved for server applications is one of the key features of Electron.
-
-As an example, to use the official AWS SDK in your application, you'd first
-install it as a dependency:
-
-```sh
-npm install --save aws-sdk
-```
-
-Then, in your Electron app, require and use the module as if you were
-building a Node.js application:
-
-```javascript
-// A ready-to-use S3 Client
-const S3 = require('aws-sdk/clients/s3')
-```
-
-There is one important caveat: Native Node.js modules (that is, modules that
-require compilation of native code before they can be used) will need to be
-compiled to be used with Electron.
-
-The vast majority of Node.js modules are _not_ native. Only 400 out of the
-~650,000 modules are native. However, if you do need native modules, please
-consult [this guide on how to recompile them for Electron][native-node].
-
-[node-docs]: https://nodejs.org/en/docs/
-[security]: ./security.md
-[native-node]: ./using-native-node-modules.md
-[share-data]: ../faq.md#how-to-share-data-between-web-pages

docs/tutorial/automated-testing-with-a-custom-driver.md

@@ -1,6 +1,6 @@
 # Automated Testing with a Custom Driver
 
-To write automated tests for your Electron app, you will need a way to "drive" your application. [Spectron](https://electronjs.org/spectron) is a commonly-used solution which lets you emulate user actions via [WebDriver](http://webdriver.io/). However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
+To write automated tests for your Electron app, you will need a way to "drive" your application. [Spectron](https://electronjs.org/spectron) is a commonly-used solution which lets you emulate user actions via [WebDriver](https://webdriver.io/). However, it's also possible to write your own custom driver using node's builtin IPC-over-STDIO. The benefit of a custom driver is that it tends to require less overhead than Spectron, and lets you expose custom methods to your test suite.
 
 To create a custom driver, we'll use Node.js' [child_process](https://nodejs.org/api/child_process.html) API. The test suite will spawn the Electron process, then establish a simple messaging protocol:
 

docs/tutorial/dark-mode.md

@@ -0,0 +1,201 @@
+# Dark Mode
+
+## Overview
+
+### Automatically update the native interfaces
+
+"Native interfaces" include the file picker, window border, dialogs, context
+menus, and more - anything where the UI comes from your operating system and
+not from your app. The default behavior is to opt into this automatic theming
+from the OS.
+
+### Automatically update your own interfaces
+
+If your app has its own dark mode, you should toggle it on and off in sync with
+the system's dark mode setting. You can do this by using the
+[prefer-color-scheme] CSS media query.
+
+### Manually update your own interfaces
+
+If you want to manually switch between light/dark modes, you can do this by
+setting the desired mode in the
+[themeSource](https://www.electronjs.org/docs/api/native-theme#nativethemethemesource)
+property of the `nativeTheme` module. This property's value will be propagated
+to your Renderer process. Any CSS rules related to `prefers-color-scheme` will
+be updated accordingly.
+
+## macOS settings
+
+In macOS 10.14 Mojave, Apple introduced a new [system-wide dark mode][system-wide-dark-mode]
+for all macOS computers. If your Electron app has a dark mode, you can make it
+follow the system-wide dark mode setting using
+[the `nativeTheme` api](../api/native-theme.md).
+
+In macOS 10.15 Catalina, Apple introduced a new "automatic" dark mode option
+for all macOS computers. In order for the `nativeTheme.shouldUseDarkColors` and
+`Tray` APIs to work correctly in this mode on Catalina, you need to use Electron
+`>=7.0.0`, or set `NSRequiresAquaSystemAppearance` to `false` in your
+`Info.plist` file for older versions. Both [Electron Packager][electron-packager]
+and [Electron Forge][electron-forge] have a
+[`darwinDarkModeSupport` option][packager-darwindarkmode-api]
+to automate the `Info.plist` changes during app build time.
+
+If you wish to opt-out while using Electron > 8.0.0, you must
+set the `NSRequiresAquaSystemAppearance` key in the `Info.plist` file to
+`true`. Please note that Electron 8.0.0 and above will not let you opt-out
+of this theming, due to the use of the macOS 10.14 SDK.
+
+## Example
+
+We'll start with a working application from the
+[Quick Start Guide](quick-start.md) and add functionality gradually.
+
+First, let's edit our interface so users can toggle between light and dark
+modes.  This basic UI contains buttons to change the `nativeTheme.themeSource`
+setting and a text element indicating which `themeSource` value is selected.
+By default, Electron follows the system's dark mode preference, so we
+will hardcode the theme source as "System".
+
+Add the following lines to the `index.html` file:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>Hello World!</title>
+    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
+    <link rel="stylesheet" type="text/css" href="./styles.css">
+</head>
+<body>
+    <h1>Hello World!</h1>
+    <p>Current theme source: <strong id="theme-source">System</strong></p>
+
+    <button id="toggle-dark-mode">Toggle Dark Mode</button>
+    <button id="reset-to-system">Reset to System Theme</button>
+
+    <script src="renderer.js"></script>
+  </body>
+</body>
+</html>
+```
+
+Next, add [event listeners](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
+that listen for `click` events on the toggle buttons. Because the `nativeTheme`
+module only exposed in the Main process, you need to set up each listener's
+callback to use IPC to send messages to and handle responses from the Main
+process:
+
+* when the "Toggle Dark Mode" button is clicked, we send the
+`dark-mode:toggle` message (event) to tell the Main process to trigger a theme
+change, and update the "Current Theme Source" label in the UI based on the
+response from the Main process.
+* when the "Reset to System Theme" button is clicked, we send the
+`dark-mode:system` message (event) to tell the Main process to use the system
+color scheme, and update the "Current Theme Source" label to `System`.
+
+To add listeners and handlers, add the following lines to the `renderer.js` file:
+
+```js
+const { ipcRenderer } = require('electron')
+
+document.getElementById('toggle-dark-mode').addEventListener('click', async () => {
+  const isDarkMode = await ipcRenderer.invoke('dark-mode:toggle')
+  document.getElementById('theme-source').innerHTML = isDarkMode ? 'Dark' : 'Light'
+})
+
+document.getElementById('reset-to-system').addEventListener('click', async () => {
+  await ipcRenderer.invoke('dark-mode:system')
+  document.getElementById('theme-source').innerHTML = 'System'
+})
+```
+
+If you run your code at this point, you'll see that your buttons don't do
+anything just yet, and your Main process will output an error like this when
+you click on your buttons:
+`Error occurred in handler for 'dark-mode:toggle': No handler registered for 'dark-mode:toggle'`
+This is expected — we haven't actually touched any `nativeTheme` code yet.
+
+Now that we're done wiring the IPC from the Renderer's side, the next step
+is to update the `main.js` file to handle events from the Renderer process.
+
+Depending on the received event, we update the
+[`nativeTheme.themeSource`](../api/native-theme.md#nativethemethemesource)
+property to apply the desired theme on the system's native UI elements
+(e.g. context menus) and propagate the preferred color scheme to the Renderer
+process:
+* Upon receiving `dark-mode:toggle`, we check if the dark theme is currently
+active using the `nativeTheme.shouldUseDarkColors` property, and set the
+`themeSource` to the opposite theme.
+* Upon receiving `dark-mode:system`, we reset the `themeSource` to `system`.
+
+```js
+const { app, BrowserWindow, ipcMain, nativeTheme } = require('electron')
+
+function createWindow () {
+  const win = new BrowserWindow({
+    width: 800,
+    height: 600,
+    webPreferences: {
+      nodeIntegration: true
+    }
+  })
+
+  win.loadFile('index.html')
+
+  ipcMain.handle('dark-mode:toggle', () => {
+    if (nativeTheme.shouldUseDarkColors) {
+      nativeTheme.themeSource = 'light'
+    } else {
+      nativeTheme.themeSource = 'dark'
+    }
+    return nativeTheme.shouldUseDarkColors
+  })
+
+  ipcMain.handle('dark-mode:system', () => {
+    nativeTheme.themeSouce = 'system'
+  })
+}
+
+app.whenReady().then(createWindow)
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') {
+    app.quit()
+  }
+})
+
+app.on('activate', () => {
+  if (BrowserWindow.getAllWindows().length === 0) {
+    createWindow()
+  }
+})
+```
+
+The final step is to add a bit of styling to enable dark mode for the web parts
+of the UI by leveraging the [`prefers-color-scheme`][prefer-color-scheme] CSS
+attribute. The value of `prefers-color-scheme` will follow your
+`nativeTheme.themeSource` setting.
+
+Create a `styles.css` file and add the following lines:
+
+```css
+@media (prefers-color-scheme: dark) {
+  body { background:  #333; color: white; }
+}
+
+@media (prefers-color-scheme: light) {
+  body { background:  #ddd; color: black; }
+}
+```
+
+After launching the Electron application, you can change modes or reset the
+theme to system default by clicking corresponding buttons:
+
+![Dark Mode](../images/dark_mode.gif)
+
+[system-wide-dark-mode]: https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/dark-mode/
+[electron-forge]: https://www.electronforge.io/
+[electron-packager]: https://github.com/electron/electron-packager
+[packager-darwindarkmode-api]: https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#darwindarkmodesupport
+[prefer-color-scheme]: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme

docs/tutorial/electron-versioning.md

@@ -16,7 +16,7 @@ npm install --save-dev electron@latest
 
 ## Version 1.x
 
-Electron versions *< 2.0* did not conform to the [semver](http://semver.org) spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
+Electron versions *< 2.0* did not conform to the [semver](https://semver.org) spec: major versions corresponded to end-user API changes, minor versions corresponded to Chromium major releases, and patch versions corresponded to new features and bug fixes. While convenient for developers merging features, it creates problems for developers of client-facing applications. The QA testing cycles of major apps like Slack, Stride, Teams, Skype, VS Code, Atom, and Desktop can be lengthy and stability is a highly desired outcome. There is a high risk in adopting new features while trying to absorb bug fixes.
 
 Here is an example of the 1.x strategy:
 

docs/tutorial/first-app.md

@@ -1,223 +0,0 @@
-# Writing Your First Electron App
-
-Electron enables you to create desktop applications with pure JavaScript by
-providing a runtime with rich native (operating system) APIs. You could see it
-as a variant of the Node.js runtime that is focused on desktop applications
-instead of web servers.
-
-This doesn't mean Electron is a JavaScript binding to graphical user interface
-(GUI) libraries. Instead, Electron uses web pages as its GUI, so you could also
-see it as a minimal Chromium browser, controlled by JavaScript.
-
-**Note**: This example is also available as a repository you can
-[download and run immediately](#trying-this-example).
-
-As far as development is concerned, an Electron application is essentially a
-Node.js application. The starting point is a `package.json` that is identical
-to that of a Node.js module. A most basic Electron app would have the following
-folder structure:
-
-```plaintext
-your-app/
-├── package.json
-├── main.js
-└── index.html
-```
-
-Create a new empty folder for your new Electron application. Open up your
-command line client and run `npm init` from that very folder.
-
-```sh
-npm init
-```
-
-npm will guide you through creating a basic `package.json` file. The script
-specified by the `main` field is the startup script of your app, which will
-run the main process. An example of your `package.json` might look like this:
-
-```json
-{
-  "name": "your-app",
-  "version": "0.1.0",
-  "main": "main.js"
-}
-```
-
-__Note__: If the `main` field is not present in `package.json`, Electron will
-attempt to load an `index.js` (as Node.js does).
-
-By default, `npm start` would run the main script with Node.js. in order to make
-it run with Electron, you can add a `start` script:
-
-```json
-{
-  "name": "your-app",
-  "version": "0.1.0",
-  "main": "main.js",
-  "scripts": {
-    "start": "electron ."
-  }
-}
-```
-
-## Installing Electron
-
-At this point, you'll need to install `electron` itself. The recommended way
-of doing so is to install it as a development dependency in your app, which
-allows you to work on multiple apps with different Electron versions. To do so,
-run the following command from your app's directory:
-
-```sh
-npm install --save-dev electron
-```
-
-Other means for installing Electron exist. Please consult the
-[installation guide](installation.md) to learn about use with proxies, mirrors,
-and custom caches.
-
-## Electron Development in a Nutshell
-
-Electron apps are developed in JavaScript using the same principles and methods
-found in Node.js development. All APIs and features found in Electron are
-accessible through the `electron` module, which can be required like any other
-Node.js module:
-
-```javascript
-const electron = require('electron')
-```
-
-The `electron` module exposes features in namespaces. As examples, the lifecycle
-of the application is managed through `electron.app`, windows can be created
-using the `electron.BrowserWindow` class. A simple `main.js` file might wait
-for the application to be ready and open a window:
-
-```javascript
-const { app, BrowserWindow } = require('electron')
-
-function createWindow () {
-  // Create the browser window.
-  const win = new BrowserWindow({
-    width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
-  })
-
-  // and load the index.html of the app.
-  win.loadFile('index.html')
-}
-
-app.whenReady().then(createWindow)
-```
-
-The `main.js` should create windows and handle all the system events your
-application might encounter. A more complete version of the above example
-might open developer tools, handle the window being closed, or re-create
-windows on macOS if the user clicks on the app's icon in the dock.
-
-```javascript
-const { app, BrowserWindow } = require('electron')
-
-function createWindow () {
-  // Create the browser window.
-  const win = new BrowserWindow({
-    width: 800,
-    height: 600,
-    webPreferences: {
-      nodeIntegration: true
-    }
-  })
-
-  // and load the index.html of the app.
-  win.loadFile('index.html')
-
-  // Open the DevTools.
-  win.webContents.openDevTools()
-}
-
-// This method will be called when Electron has finished
-// initialization and is ready to create browser windows.
-// Some APIs can only be used after this event occurs.
-app.whenReady().then(createWindow)
-
-// Quit when all windows are closed, except on macOS. There, it's common
-// for applications and their menu bar to stay active until the user quits
-// explicitly with Cmd + Q.
-app.on('window-all-closed', () => {
-  if (process.platform !== 'darwin') {
-    app.quit()
-  }
-})
-
-app.on('activate', () => {
-  // On macOS it's common to re-create a window in the app when the
-  // dock icon is clicked and there are no other windows open.
-  if (BrowserWindow.getAllWindows().length === 0) {
-    createWindow()
-  }
-})
-
-// In this file you can include the rest of your app's specific main process
-// code. You can also put them in separate files and require them here.
-```
-
-Finally the `index.html` is the web page you want to show:
-
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8">
-    <title>Hello World!</title>
-    <!-- https://electronjs.org/docs/tutorial/security#csp-meta-tag -->
-    <meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-inline';" />
-  </head>
-  <body>
-    <h1>Hello World!</h1>
-    We are using node <script>document.write(process.versions.node)</script>,
-    Chrome <script>document.write(process.versions.chrome)</script>,
-    and Electron <script>document.write(process.versions.electron)</script>.
-  </body>
-</html>
-```
-
-## Running Your App
-
-Once you've created your initial `main.js`, `index.html`, and `package.json`
-files, you can try your app by running `npm start` from your application's
-directory.
-
-**Note**: If you are building this project without downloading the example
-repository, your `start` script in `package.json` should look like this
-
-```json
-  "scripts": {
-    "start": "electron ."
-  }
-```
-
-## Trying this Example
-
-Clone and run the code in this tutorial by using the
-[`electron/electron-quick-start`][quick-start] repository.
-
-**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
-
-```sh
-# Clone the repository
-$ git clone https://github.com/electron/electron-quick-start
-# Go into the repository
-$ cd electron-quick-start
-# Install dependencies
-$ npm install
-# Run the app
-$ npm start
-```
-
-For a list of boilerplates and tools to kick-start your development process,
-see the [Boilerplates and CLIs documentation][boilerplates].
-
-[share-data]: ../faq.md#how-to-share-data-between-web-pages
-[quick-start]: https://github.com/electron/electron-quick-start
-[boilerplates]: ./boilerplates-and-clis.md

docs/tutorial/fuses.md

@@ -0,0 +1,54 @@
+# Electron Fuses
+
+> Package time feature toggles
+
+## What are fuses?
+
+For a subset of Electron functionality it makes sense to disable certain features for an entire application.  For example, 99% of apps don't make use of `ELECTRON_RUN_AS_NODE`, these applications want to be able to ship a binary that is incapable of using that feature.  We also don't want Electron consumers building Electron from source as that is both a massive technical challenge and has a high cost of both time and money.
+
+Fuses are the solution to this problem, at a high level they are "magic bits" in the Electron binary that can be flipped when packaging your Electron app to enable / disable certain features / restrictions.  Because they are flipped at package time before you code sign your app the OS becomes responsible for ensuring those bits aren't flipped back via OS level code signing validation (Gatekeeper / App Locker).
+
+## How do I flip the fuses?
+
+### The easy way
+
+We've made a handy module `@electron/fuses` to make flipping these fuses easy.  Check out the README of that module for more details on usage and potential error cases.
+
+```js
+require('@electron/fuses').flipFuses(
+  // Path to electron
+  require('electron'),
+  // Fuses to flip
+  {
+    runAsNode: false
+  }
+)
+```
+
+### The hard way
+
+#### Quick Glossary
+
+* **Fuse Wire**: A sequence of bytes in the Electron binary used to control the fuses
+* **Sentinel**: A static known sequence of bytes you can use to locate the fuse wire
+* **Fuse Schema**: The format / allowed values for the fuse wire
+
+Manually flipping fuses requires editing the Electron binary and modifying the fuse wire to be the sequence of bytes that represent the state of the fuses you want.
+
+Somewhere in the Electron binary there will be a sequence of bytes that look like this:
+
+```text
+| ...binary | sentinel_bytes | fuse_version | fuse_wire_length | fuse_wire | ...binary |
+```
+
+* `sentinel_bytes` is always this exact string `dL7pKGdnNz796PbbjQWNKmHXBZaB9tsX`
+* `fuse_version` is a single byte whose unsigned integer value represents the version of the fuse schema
+* `fuse_wire_length` is a single byte whose unsigned integer value represents the number of fuses in the following fuse wire
+* `fuse_wire` is a sequence of N bytes, each byte represents a single fuse and its state.
+  * "0" (0x30) indicates the fuse is disabled
+  * "1" (0x31) indicates the fuse is enabled
+  * "r" (0x72) indicates the fuse has been removed and changing the byte to either 1 or 0 will have no effect.
+
+To flip a fuse you find its position in the fuse wire and change it to "0" or "1" depending on the state you'd like.
+
+You can view the current schema [here](https://github.com/electron/electron/blob/master/build/fuses/fuses.json).

docs/tutorial/keyboard-shortcuts.md

@@ -1,62 +1,131 @@
 # Keyboard Shortcuts
 
-> Configure local and global keyboard shortcuts
+## Overview
 
-## Local Shortcuts
+This feature allows you to configure local and global keyboard shortcuts
+for your Electron application.
 
-You can use the [Menu] module to configure keyboard shortcuts that will
-be triggered only when the app is focused. To do so, specify an
-[`accelerator`] property when creating a [MenuItem].
+## Example
+
+### Local Shortcuts
+
+Local keyboard shortcuts are triggered only when the application is focused.
+To configure a local keyboard shortcut, you need to specify an [`accelerator`]
+property when creating a [MenuItem] within the [Menu] module.
+
+Starting with a working application from the
+[Quick Start Guide](quick-start.md), update the `main.js` file with the
+following lines:
 
 ```js
 const { Menu, MenuItem } = require('electron')
+
 const menu = new Menu()
-
 menu.append(new MenuItem({
-  label: 'Print',
-  accelerator: 'CmdOrCtrl+P',
-  click: () => { console.log('time to print stuff') }
+  label: 'Electron',
+  submenu: [{
+    role: 'help',
+    accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Alt+Shift+I',
+    click: () => { console.log('Electron rocks!') }
+  }]
 }))
+
+Menu.setApplicationMenu(menu)
 ```
 
-You can configure different key combinations based on the user's operating system.
+> NOTE: In the code above, you can see that the accelerator differs based on the
+user's operating system. For MacOS, it is `Alt+Cmd+I`, whereas for Linux and
+Windows, it is `Alt+Shift+I`.
 
-```js
-{
-  accelerator: process.platform === 'darwin' ? 'Alt+Cmd+I' : 'Ctrl+Shift+I'
-}
-```
+After launching the Electron application, you should see the application menu
+along with the local shortcut you just defined:
 
-## Global Shortcuts
+![Menu with a local shortcut](../images/local-shortcut.png)
 
-You can use the [globalShortcut] module to detect keyboard events even when
-the application does not have keyboard focus.
+If you click `Help` or press the defined accelerator and then open the terminal
+that you ran your Electron application from, you will see the message that was
+generated after triggering the `click` event: "Electron rocks!".
+
+### Global Shortcuts
+
+To configure a global keyboard shortcut, you need to use the [globalShortcut]
+module to detect keyboard events even when the application does not have
+keyboard focus.
+
+Starting with a working application from the
+[Quick Start Guide](quick-start.md), update the `main.js` file with the
+following lines:
 
 ```js
 const { app, globalShortcut } = require('electron')
 
 app.whenReady().then(() => {
-  globalShortcut.register('CommandOrControl+X', () => {
-    console.log('CommandOrControl+X is pressed')
+  globalShortcut.register('Alt+CommandOrControl+I', () => {
+    console.log('Electron loves global shortcuts!')
   })
-})
+}).then(createWindow)
 ```
 
-## Shortcuts within a BrowserWindow
+> NOTE: In the code above, the `CommandOrControl` combination uses `Command`
+on macOS and `Control` on Windows/Linux.
 
-If you want to handle keyboard shortcuts for a [BrowserWindow], you can use the `keyup` and `keydown` event listeners on the window object inside the renderer process.
+After launching the Electron application, if you press the defined key
+combination then open the terminal that you ran your Electron application from,
+you will see that Electron loves global shortcuts!
+
+### Shortcuts within a BrowserWindow
+
+#### Using web APIs
+
+If you want to handle keyboard shortcuts within a [BrowserWindow], you can
+listen for the `keyup` and `keydown` [DOM events][dom-events] inside the
+renderer process using the [addEventListener() API][addEventListener-api].
 
 ```js
 window.addEventListener('keyup', doSomething, true)
 ```
 
-Note the third parameter `true` which means the listener will always receive key presses before other listeners so they can't have `stopPropagation()` called on them.
+Note the third parameter `true` indicates that the listener will always receive
+key presses before other listeners so they can't have `stopPropagation()`
+called on them.
+
+#### Intercepting events in the main process
 
 The [`before-input-event`](../api/web-contents.md#event-before-input-event) event
 is emitted before dispatching `keydown` and `keyup` events in the page. It can
 be used to catch and handle custom shortcuts that are not visible in the menu.
 
-If you don't want to do manual shortcut parsing there are libraries that do advanced key detection such as [mousetrap].
+##### Example
+
+Starting with a working application from the
+[Quick Start Guide](quick-start.md), update the `main.js` file with the
+following lines:
+
+```js
+const { app, BrowserWindow } = require('electron')
+
+app.whenReady().then(() => {
+  const win = new BrowserWindow({ width: 800, height: 600, webPreferences: { nodeIntegration: true } })
+
+  win.loadFile('index.html')
+  win.webContents.on('before-input-event', (event, input) => {
+    if (input.control && input.key.toLowerCase() === 'i') {
+      console.log('Pressed Control+I')
+      event.preventDefault()
+    }
+  })
+})
+```
+
+After launching the Electron application, if you open the terminal that you ran
+your Electron application from and press `Ctrl+I` key combination, you will
+see that this key combination was successfully intercepted.
+
+#### Using third-party libraries
+
+If you don't want to do manual shortcut parsing, there are libraries that do
+advanced key detection, such as [mousetrap]. Below are examples of usage of the
+`mousetrap` running in the Renderer process:
 
 ```js
 Mousetrap.bind('4', () => { console.log('4') })
@@ -90,3 +159,5 @@ Mousetrap.bind('up up down down left right left right b a enter', () => {
 [`accelerator`]: ../api/accelerator.md
 [BrowserWindow]: ../api/browser-window.md
 [mousetrap]: https://github.com/ccampbell/mousetrap
+[dom-events]: https://developer.mozilla.org/en-US/docs/Web/Events
+[addEventListener-api]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

docs/tutorial/linux-desktop-actions.md

@@ -1,17 +1,21 @@
 # Custom Linux Desktop Launcher Actions
 
-On many Linux environments, you can add custom entries to its launcher
-by modifying the `.desktop` file. For Canonical's Unity documentation,
-see [Adding Shortcuts to a Launcher][unity-launcher]. For details on a
-more generic implementation, see the [freedesktop.org Specification][spec].
+## Overview
 
-__Launcher shortcuts of Audacious:__
+On many Linux environments, you can add custom entries to the system launcher
+by modifying the `.desktop` file. For Canonical's Unity documentation, see
+[Adding Shortcuts to a Launcher][unity-launcher]. For details on a more generic
+implementation, see the [freedesktop.org Specification][spec].
 
 ![audacious][audacious-launcher]
 
-Generally speaking, shortcuts are added by providing a `Name` and `Exec`
-property for each entry in the shortcuts menu. Unity will execute the
-`Exec` field once clicked by the user. The format is as follows:
+> NOTE: The screenshot above is an example of launcher shortcuts in Audacious
+audio player
+
+To create a shortcut, you need to provide `Name` and `Exec` properties for the
+entry you want to add to the shortcut menu. Unity will execute the command
+defined in the `Exec` field after the user clicked the shortcut menu item.
+An example of the `.desktop` file may look as follows:
 
 ```plaintext
 Actions=PlayPause;Next;Previous
@@ -32,8 +36,8 @@ Exec=audacious -r
 OnlyShowIn=Unity;
 ```
 
-Unity's preferred way of telling your application what to do is to use
-parameters. You can find these in your app in the global variable
+The preferred way for Unity to instruct your application on what to do is using
+parameters. You can find them in your application in the global variable
 `process.argv`.
 
 [unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher

docs/tutorial/mac-app-store-submission-guide.md

@@ -242,14 +242,14 @@ Electron uses following cryptographic algorithms:
 * ECDH - ANS X9.63–2001
 * HKDF - [NIST SP 800-56C](https://csrc.nist.gov/publications/nistpubs/800-56C/SP-800-56C.pdf)
 * PBKDF2 - [RFC 2898](https://tools.ietf.org/html/rfc2898)
-* RSA - [RFC 3447](http://www.ietf.org/rfc/rfc3447)
+* RSA - [RFC 3447](https://www.ietf.org/rfc/rfc3447)
 * SHA - [FIPS 180-4](https://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf)
 * Blowfish - https://www.schneier.com/cryptography/blowfish/
 * CAST - [RFC 2144](https://tools.ietf.org/html/rfc2144), [RFC 2612](https://tools.ietf.org/html/rfc2612)
 * DES - [FIPS 46-3](https://csrc.nist.gov/publications/fips/fips46-3/fips46-3.pdf)
 * DH - [RFC 2631](https://tools.ietf.org/html/rfc2631)
 * DSA - [ANSI X9.30](https://webstore.ansi.org/RecordDetail.aspx?sku=ANSI+X9.30-1%3A1997)
-* EC - [SEC 1](http://www.secg.org/sec1-v2.pdf)
+* EC - [SEC 1](https://www.secg.org/sec1-v2.pdf)
 * IDEA - "On the Design and Security of Block Ciphers" book by X. Lai
 * MD2 - [RFC 1319](https://tools.ietf.org/html/rfc1319)
 * MD4 - [RFC 6150](https://tools.ietf.org/html/rfc6150)
@@ -257,7 +257,7 @@ Electron uses following cryptographic algorithms:
 * MDC2 - [ISO/IEC 10118-2](https://wiki.openssl.org/index.php/Manual:Mdc2(3))
 * RC2 - [RFC 2268](https://tools.ietf.org/html/rfc2268)
 * RC4 - [RFC 4345](https://tools.ietf.org/html/rfc4345)
-* RC5 - http://people.csail.mit.edu/rivest/Rivest-rc5rev.pdf
+* RC5 - https://people.csail.mit.edu/rivest/Rivest-rc5rev.pdf
 * RIPEMD - [ISO/IEC 10118-3](https://webstore.ansi.org/RecordDetail.aspx?sku=ISO%2FIEC%2010118-3:2004)
 
 [developer-program]: https://developer.apple.com/support/compare-memberships/

docs/tutorial/macos-dock.md

@@ -1,10 +1,11 @@
 # macOS Dock
 
+## Overview
+
 Electron has APIs to configure the app's icon in the macOS Dock. A macOS-only
-API exists to create a custom dock menu, but
-Electron also uses the app's dock icon to implement cross-platform features
-like [recent documents][recent-documents] and
-[application progress][progress-bar].
+API exists to create a custom dock menu, but Electron also uses the app dock
+icon as the entry point for cross-platform features like
+[recent documents][recent-documents] and [application progress][progress-bar].
 
 The custom dock is commonly used to add shortcuts to tasks the user wouldn't
 want to open the whole app window for.
@@ -13,8 +14,15 @@ __Dock menu of Terminal.app:__
 
 ![Dock Menu][dock-menu-image]
 
-To set your custom dock menu, you can use the `app.dock.setMenu` API, which is
-only available on macOS:
+To set your custom dock menu, you need to use the
+[`app.dock.setMenu`](../api/dock.md#docksetmenumenu-macos) API,
+which is only available on macOS.
+
+## Example
+
+Starting with a working application from the
+ [Quick Start Guide](quick-start.md), update the `main.js` file with the
+ following lines:
 
 ```javascript
 const { app, Menu } = require('electron')
@@ -33,9 +41,16 @@ const dockMenu = Menu.buildFromTemplate([
   { label: 'New Command...' }
 ])
 
-app.dock.setMenu(dockMenu)
+app.whenReady().then(() => {
+  app.dock.setMenu(dockMenu)
+})
 ```
 
+After launching the Electron application, right click the application icon.
+You should see the custom menu you just defined:
+
+![macOS dock menu](../images/macos-dock-menu.png)
+
 [dock-menu-image]: https://cloud.githubusercontent.com/assets/639601/5069962/6032658a-6e9c-11e4-9953-aa84006bdfff.png
 [recent-documents]: ./recent-documents.md
 [progress-bar]: ./progress-bar.md