diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 0822c140e2cd..3a65cd1249f8 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,8 +2,8 @@ As a member project of the OpenJS Foundation, Electron uses [Contributor Covenant v2.0](https://contributor-covenant.org/version/2/0/code_of_conduct) as their code of conduct. The full text is included [below](#contributor-covenant-code-of-conduct) in English, and translations are available from the Contributor Covenant organisation: -- [contributor-covenant.org/translations](https://www.contributor-covenant.org/translations) -- [github.com/ContributorCovenant](https://github.com/ContributorCovenant/contributor_covenant/tree/release/content/version/2/0) +* [contributor-covenant.org/translations](https://www.contributor-covenant.org/translations) +* [github.com/ContributorCovenant](https://github.com/ContributorCovenant/contributor_covenant/tree/release/content/version/2/0) ## Contributor Covenant Code of Conduct diff --git a/docs/api/command-line-switches.md b/docs/api/command-line-switches.md index 4d9deec60945..902e2c836c84 100644 --- a/docs/api/command-line-switches.md +++ b/docs/api/command-line-switches.md @@ -65,12 +65,12 @@ Forces the maximum disk space to be used by the disk cache, in bytes. Enables caller stack logging for the following APIs (filtering events): -- `desktopCapturer.getSources()` / `desktop-capturer-get-sources` -- `remote.require()` / `remote-require` -- `remote.getGlobal()` / `remote-get-builtin` -- `remote.getBuiltin()` / `remote-get-global` -- `remote.getCurrentWindow()` / `remote-get-current-window` -- `remote.getCurrentWebContents()` / `remote-get-current-web-contents` +* `desktopCapturer.getSources()` / `desktop-capturer-get-sources` +* `remote.require()` / `remote-require` +* `remote.getGlobal()` / `remote-get-builtin` +* `remote.getBuiltin()` / `remote-get-global` +* `remote.getCurrentWindow()` / `remote-get-current-window` +* `remote.getCurrentWebContents()` / `remote-get-current-web-contents` ### --enable-logging diff --git a/docs/api/process.md b/docs/api/process.md index d3de0264c48b..ec77bda8b86f 100644 --- a/docs/api/process.md +++ b/docs/api/process.md @@ -12,28 +12,28 @@ It adds the following events, properties, and methods: In sandboxed renderers the `process` object contains only a subset of the APIs: -- `crash()` -- `hang()` -- `getCreationTime()` -- `getHeapStatistics()` -- `getBlinkMemoryInfo()` -- `getProcessMemoryInfo()` -- `getSystemMemoryInfo()` -- `getSystemVersion()` -- `getCPUUsage()` -- `getIOCounters()` -- `argv` -- `execPath` -- `env` -- `pid` -- `arch` -- `platform` -- `sandboxed` -- `type` -- `version` -- `versions` -- `mas` -- `windowsStore` +* `crash()` +* `hang()` +* `getCreationTime()` +* `getHeapStatistics()` +* `getBlinkMemoryInfo()` +* `getProcessMemoryInfo()` +* `getSystemMemoryInfo()` +* `getSystemVersion()` +* `getCPUUsage()` +* `getIOCounters()` +* `argv` +* `execPath` +* `env` +* `pid` +* `arch` +* `platform` +* `sandboxed` +* `type` +* `version` +* `versions` +* `mas` +* `windowsStore` ## Events diff --git a/docs/api/remote.md b/docs/api/remote.md index 01f963673505..063330550d3a 100644 --- a/docs/api/remote.md +++ b/docs/api/remote.md @@ -36,8 +36,8 @@ you can use [webContents.executeJavaScript](web-contents.md#contentsexecutejavas **Note:** The remote module can be disabled for security reasons in the following contexts: -- [`BrowserWindow`](browser-window.md) - by setting the `enableRemoteModule` option to `false`. -- [``](webview-tag.md) - by setting the `enableremotemodule` attribute to `false`. +* [`BrowserWindow`](browser-window.md) - by setting the `enableRemoteModule` option to `false`. +* [``](webview-tag.md) - by setting the `enableremotemodule` attribute to `false`. ## Remote Objects diff --git a/docs/api/session.md b/docs/api/session.md index 5db617e9ba04..fceafaee1a57 100644 --- a/docs/api/session.md +++ b/docs/api/session.md @@ -101,8 +101,8 @@ Returns: Emitted after an extension is loaded. This occurs whenever an extension is added to the "enabled" set of extensions. This includes: -- Extensions being loaded from `Session.loadExtension`. -- Extensions being reloaded: +* Extensions being loaded from `Session.loadExtension`. +* Extensions being reloaded: * from a crash. * if the extension requested it ([`chrome.runtime.reload()`](https://developer.chrome.com/extensions/runtime#method-reload)). diff --git a/docs/api/window-open.md b/docs/api/window-open.md index 2323731d1cda..8ff7aae726b9 100644 --- a/docs/api/window-open.md +++ b/docs/api/window-open.md @@ -3,8 +3,8 @@ There are several ways to control how windows are created from trusted or untrusted content within a renderer. Windows can be created from the renderer in two ways: -- clicking on links or submitting forms adorned with `target=_blank` -- JavaScript calling `window.open()` +* clicking on links or submitting forms adorned with `target=_blank` +* JavaScript calling `window.open()` In non-sandboxed renderers, or when `nativeWindowOpen` is false (the default), this results in the creation of a [`BrowserWindowProxy`](browser-window-proxy.md), a light wrapper around diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index d527648c58ac..73525e37cd9d 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -6,11 +6,11 @@ Breaking changes will be documented here, and deprecation warnings added to JS c This document uses the following convention to categorize breaking changes: -- **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception. -- **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown. -- **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value. -- **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release. -- **Removed:** An API or feature was removed, and is no longer supported by Electron. +* **API Changed:** An API was changed in such a way that code that has not been updated is guaranteed to throw an exception. +* **Behavior Changed:** The behavior of Electron has changed, but not in such a way that an exception will necessarily be thrown. +* **Default Changed:** Code depending on the old default may break, not necessarily throwing an exception. The old behavior can be restored by explicitly specifying the value. +* **Deprecated:** An API was marked as deprecated. The API will continue to function, but will emit a deprecation warning, and will be removed in a future release. +* **Removed:** An API or feature was removed, and is no longer supported by Electron. ## Planned Breaking API Changes (13.0) @@ -48,12 +48,12 @@ For more details see: https://github.com/electron/electron/issues/23506 The following `crashReporter` methods are no longer available in the renderer process: -- `crashReporter.start` -- `crashReporter.getLastCrashReport` -- `crashReporter.getUploadedReports` -- `crashReporter.getUploadToServer` -- `crashReporter.setUploadToServer` -- `crashReporter.getCrashesDirectory` +* `crashReporter.start` +* `crashReporter.getLastCrashReport` +* `crashReporter.getUploadedReports` +* `crashReporter.getUploadToServer` +* `crashReporter.setUploadToServer` +* `crashReporter.getCrashesDirectory` They should be called only from the main process. @@ -144,12 +144,12 @@ app.getPath('crashDumps') Calling the following `crashReporter` methods from the renderer process is deprecated: -- `crashReporter.start` -- `crashReporter.getLastCrashReport` -- `crashReporter.getUploadedReports` -- `crashReporter.getUploadToServer` -- `crashReporter.setUploadToServer` -- `crashReporter.getCrashesDirectory` +* `crashReporter.start` +* `crashReporter.getLastCrashReport` +* `crashReporter.getUploadedReports` +* `crashReporter.getUploadToServer` +* `crashReporter.setUploadToServer` +* `crashReporter.getCrashesDirectory` The only non-deprecated methods remaining in the `crashReporter` module in the renderer are `addExtraParameter`, `removeExtraParameter` and `getParameters`. @@ -314,7 +314,7 @@ Clone Algorithm][SCA], the same algorithm used to serialize messages for `postMessage`. This brings about a 2x performance improvement for large messages, but also brings some breaking changes in behavior. -- Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any +* Sending Functions, Promises, WeakMaps, WeakSets, or objects containing any such values, over IPC will now throw an exception, instead of silently converting the functions to `undefined`. @@ -328,21 +328,21 @@ ipcRenderer.send('channel', { value: 3, someFunction: () => {} }) // => throws Error("() => {} could not be cloned.") ``` -- `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead +* `NaN`, `Infinity` and `-Infinity` will now be correctly serialized, instead of being converted to `null`. -- Objects containing cyclic references will now be correctly serialized, +* Objects containing cyclic references will now be correctly serialized, instead of being converted to `null`. -- `Set`, `Map`, `Error` and `RegExp` values will be correctly serialized, +* `Set`, `Map`, `Error` and `RegExp` values will be correctly serialized, instead of being converted to `{}`. -- `BigInt` values will be correctly serialized, instead of being converted to +* `BigInt` values will be correctly serialized, instead of being converted to `null`. -- Sparse arrays will be serialized as such, instead of being converted to dense +* Sparse arrays will be serialized as such, instead of being converted to dense arrays with `null`s. -- `Date` objects will be transferred as `Date` objects, instead of being +* `Date` objects will be transferred as `Date` objects, instead of being converted to their ISO string representation. -- Typed Arrays (such as `Uint8Array`, `Uint16Array`, `Uint32Array` and so on) +* Typed Arrays (such as `Uint8Array`, `Uint16Array`, `Uint32Array` and so on) will be transferred as such, instead of being converted to Node.js `Buffer`. -- Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can +* Node.js `Buffer` objects will be transferred as `Uint8Array`s. You can convert a `Uint8Array` back to a Node.js `Buffer` by wrapping the underlying `ArrayBuffer`: diff --git a/docs/development/coding-style.md b/docs/development/coding-style.md index 2eb0eb3a796b..324513ff8652 100644 --- a/docs/development/coding-style.md +++ b/docs/development/coding-style.md @@ -66,11 +66,11 @@ formatted correctly. Electron APIs uses the same capitalization scheme as Node.js: -- When the module itself is a class like `BrowserWindow`, use `PascalCase`. -- When the module is a set of APIs, like `globalShortcut`, use `camelCase`. -- When the API is a property of object, and it is complex enough to be in a +* When the module itself is a class like `BrowserWindow`, use `PascalCase`. +* When the module is a set of APIs, like `globalShortcut`, use `camelCase`. +* When the API is a property of object, and it is complex enough to be in a separate chapter like `win.webContents`, use `mixedCase`. -- For other non-module APIs, use natural titles, like ` Tag` or +* For other non-module APIs, use natural titles, like ` Tag` or `Process Object`. When creating a new API, it is preferred to use getters and setters instead of diff --git a/docs/development/pull-requests.md b/docs/development/pull-requests.md index b3f8350ead9a..562ddfaa2b00 100644 --- a/docs/development/pull-requests.md +++ b/docs/development/pull-requests.md @@ -91,29 +91,29 @@ Before a pull request can be merged, it **must** have a pull request title with Examples of commit messages with semantic prefixes: -- `fix: don't overwrite prevent_default if default wasn't prevented` -- `feat: add app.isPackaged() method` -- `docs: app.isDefaultProtocolClient is now available on Linux` +* `fix: don't overwrite prevent_default if default wasn't prevented` +* `feat: add app.isPackaged() method` +* `docs: app.isDefaultProtocolClient is now available on Linux` Common prefixes: -- fix: A bug fix -- feat: A new feature -- docs: Documentation changes -- test: Adding missing tests or correcting existing tests -- build: Changes that affect the build system -- ci: Changes to our CI configuration files and scripts -- perf: A code change that improves performance -- refactor: A code change that neither fixes a bug nor adds a feature -- style: Changes that do not affect the meaning of the code (linting) -- vendor: Bumping a dependency like libchromiumcontent or node +* fix: A bug fix +* feat: A new feature +* docs: Documentation changes +* test: Adding missing tests or correcting existing tests +* build: Changes that affect the build system +* ci: Changes to our CI configuration files and scripts +* perf: A code change that improves performance +* refactor: A code change that neither fixes a bug nor adds a feature +* style: Changes that do not affect the meaning of the code (linting) +* vendor: Bumping a dependency like libchromiumcontent or node Other things to keep in mind when writing a commit message: 1. The first line should: - - contain a short description of the change (preferably 50 characters or less, + * contain a short description of the change (preferably 50 characters or less, and no more than 72 characters) - - be entirely in lowercase with the exception of proper nouns, acronyms, and + * be entirely in lowercase with the exception of proper nouns, acronyms, and the words that refer to code, like function/variable names 2. Keep the second line blank. 3. Wrap all other lines at 72 columns. diff --git a/docs/styleguide.md b/docs/styleguide.md index 80f6699b7650..cd912cafb43a 100644 --- a/docs/styleguide.md +++ b/docs/styleguide.md @@ -49,6 +49,7 @@ For API references, there are exceptions to this rule. * No nesting lists more than 2 levels (due to the markdown renderer). * All `js` and `javascript` code blocks are linted with [standard-markdown](https://www.npmjs.com/package/standard-markdown). +* For unordered lists, use asterisks instead of dashes ## Picking words diff --git a/docs/tutorial/code-signing.md b/docs/tutorial/code-signing.md index e869416d3515..f38edd50f69e 100644 --- a/docs/tutorial/code-signing.md +++ b/docs/tutorial/code-signing.md @@ -196,11 +196,11 @@ it may be worth your time to shop around. Popular resellers include: There are a number of tools for signing your packaged app: -- [`electron-winstaller`] will generate an installer for windows and sign it for +* [`electron-winstaller`] will generate an installer for windows and sign it for you -- [`electron-forge`] can sign installers it generates through the +* [`electron-forge`] can sign installers it generates through the Squirrel.Windows or MSI targets. -- [`electron-builder`] can sign some of its windows targets +* [`electron-builder`] can sign some of its windows targets ## Windows Store diff --git a/docs/tutorial/electron-versioning.md b/docs/tutorial/electron-versioning.md index decd85f5d0cc..3f284c2cb3ac 100644 --- a/docs/tutorial/electron-versioning.md +++ b/docs/tutorial/electron-versioning.md @@ -145,7 +145,7 @@ We seek to increase clarity at all levels of the update and releases process. St # Versioned `master` -- The `master` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json` -- Release branches are never merged back to master -- Release branches _do_ contain the correct version in their `package.json` -- As soon as a release branch is cut for a major, master must be bumped to the next major. I.e. `master` is always versioned as the next theoretical release branch +* The `master` branch will always contain the next major version `X.0.0-nightly.DATE` in its `package.json` +* Release branches are never merged back to master +* Release branches _do_ contain the correct version in their `package.json` +* As soon as a release branch is cut for a major, master must be bumped to the next major. I.e. `master` is always versioned as the next theoretical release branch diff --git a/docs/tutorial/support.md b/docs/tutorial/support.md index a50a8f4f3062..1cc3a93180b1 100644 --- a/docs/tutorial/support.md +++ b/docs/tutorial/support.md @@ -10,21 +10,21 @@ for answers to questions, or to join in discussion with other developers who use Electron, you can interact with the community in these locations: -- [`Electron's Discord`](https://discord.com/invite/electron) has channels for: - - Getting help - - Ecosystem apps like [Electron Forge](https://github.com/electron-userland/electron-forge) and [Electron Fiddle](https://github.com/electron/fiddle) - - Sharing ideas with other Electron app developers - - And more! -- [`electron`](https://discuss.atom.io/c/electron) category on the Atom forums -- `#atom-shell` channel on Freenode -- `#electron` channel on [Atom's Slack](https://discuss.atom.io/t/join-us-on-slack/16638?source_topic_id=25406) -- [`electron-ru`](https://telegram.me/electron_ru) *(Russian)* -- [`electron-br`](https://electron-br.slack.com) *(Brazilian Portuguese)* -- [`electron-kr`](https://electron-kr.github.io/electron-kr) *(Korean)* -- [`electron-jp`](https://electron-jp.slack.com) *(Japanese)* -- [`electron-tr`](https://electron-tr.herokuapp.com) *(Turkish)* -- [`electron-id`](https://electron-id.slack.com) *(Indonesia)* -- [`electron-pl`](https://electronpl.github.io) *(Poland)* +* [`Electron's Discord`](https://discord.com/invite/electron) has channels for: + * Getting help + * Ecosystem apps like [Electron Forge](https://github.com/electron-userland/electron-forge) and [Electron Fiddle](https://github.com/electron/fiddle) + * Sharing ideas with other Electron app developers + * And more! +* [`electron`](https://discuss.atom.io/c/electron) category on the Atom forums +* `#atom-shell` channel on Freenode +* `#electron` channel on [Atom's Slack](https://discuss.atom.io/t/join-us-on-slack/16638?source_topic_id=25406) +* [`electron-ru`](https://telegram.me/electron_ru) *(Russian)* +* [`electron-br`](https://electron-br.slack.com) *(Brazilian Portuguese)* +* [`electron-kr`](https://electron-kr.github.io/electron-kr) *(Korean)* +* [`electron-jp`](https://electron-jp.slack.com) *(Japanese)* +* [`electron-tr`](https://electron-tr.herokuapp.com) *(Turkish)* +* [`electron-id`](https://electron-id.slack.com) *(Indonesia)* +* [`electron-pl`](https://electronpl.github.io) *(Poland)* If you'd like to contribute to Electron, see the [contributing document](https://github.com/electron/electron/blob/master/CONTRIBUTING.md). @@ -64,9 +64,9 @@ until the maintainers feel the maintenance burden is too high to continue doing ### Currently supported versions -- 11.x.y -- 10.x.y -- 9.x.y +* 11.x.y +* 10.x.y +* 9.x.y ### End-of-life diff --git a/docs/tutorial/using-native-node-modules.md b/docs/tutorial/using-native-node-modules.md index 8d47cd9d53f2..ea362858df58 100644 --- a/docs/tutorial/using-native-node-modules.md +++ b/docs/tutorial/using-native-node-modules.md @@ -129,13 +129,13 @@ should look like this: In particular, it's important that: -- you link against `node.lib` from _Electron_ and not Node. If you link against +* you link against `node.lib` from _Electron_ and not Node. If you link against the wrong `node.lib` you will get load-time errors when you require the module in Electron. -- you include the flag `/DELAYLOAD:node.exe`. If the `node.exe` link is not +* you include the flag `/DELAYLOAD:node.exe`. If the `node.exe` link is not delayed, then the delay-load hook won't get a chance to fire and the node symbols won't be correctly resolved. -- `win_delay_load_hook.obj` is linked directly into the final DLL. If the hook +* `win_delay_load_hook.obj` is linked directly into the final DLL. If the hook is set up in a dependent DLL, it won't fire at the right time. See [`node-gyp`](https://github.com/nodejs/node-gyp/blob/e2401e1395bef1d3c8acec268b42dc5fb71c4a38/src/win_delay_load_hook.cc)