mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: categorize breaking changes (#22834)

Browse source 
Co-authored-by: John Kleinschmidt <jkleinsc@github.com>
This commit is contained in:
Jeremy Apthorp 2020-03-26 10:57:55 -07:00 • committed by GitHub
parent e73d5e3db5
commit b1f4ac00f0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 45 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
docs/breaking-changes.md
View file

@ -2,13 +2,19 @@
Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least [one major version](tutorial/electron-versioning.md#semver) before the change is made. Breaking changes will be documented here, and deprecation warnings added to JS code where possible, at least [one major version](tutorial/electron-versioning.md#semver) before the change is made.
## `FIXME` comments ### Types of Breaking Changes
The `FIXME` string is used in code comments to denote things that should be fixed for future releases. See https://github.com/electron/electron/search?q=fixme 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.
## Planned Breaking API Changes (10.0) ## Planned Breaking API Changes (10.0)
### Browser Window Affinity ### Removed: Browser Window Affinity
The `affinity` option when constructing a new `BrowserWindow` will be removed The `affinity` option when constructing a new `BrowserWindow` will be removed
as part of our plan to more closely align with Chromiums process model for security, as part of our plan to more closely align with Chromiums process model for security,
@ -16,7 +22,7 @@ performance and maintainability.
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397). For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
### `enableRemoteModule` defaults to `false` ### Default Changed: `enableRemoteModule` defaults to `false`
In Electron 9, using the remote module without explicitly enabling it via the In Electron 9, using the remote module without explicitly enabling it via the
`enableRemoteModule` WebPreferences option began emitting a warning. In `enableRemoteModule` WebPreferences option began emitting a warning. In
@ -36,7 +42,7 @@ module](https://medium.com/@nornagon/electrons-remote-module-considered-harmful-
## Planned Breaking API Changes (9.0) ## Planned Breaking API Changes (9.0)
### Loading non-context-aware native modules in the renderer process ### Default Changed: Loading non-context-aware native modules in the renderer process is disabled by default
As of Electron 9 we do not allow loading of non-context-aware native modules in As of Electron 9 we do not allow loading of non-context-aware native modules in
the renderer process. This is to improve security, performance and maintainability the renderer process. This is to improve security, performance and maintainability
@ -48,7 +54,7 @@ you should plan to update your native modules to be context aware.
For more detailed information see [#18397](https://github.com/electron/electron/issues/18397). For more detailed information see [#18397](https://github.com/electron/electron/issues/18397).
### `<webview>.getWebContents()` ### Removed: `<webview>.getWebContents()`
This API, which was deprecated in Electron 8.0, is now removed. This API, which was deprecated in Electron 8.0, is now removed.
@ -60,7 +66,7 @@ const { remote } = require('electron')
remote.webContents.fromId(webview.getWebContentsId()) remote.webContents.fromId(webview.getWebContentsId())
``` ```
### `webFrame.setLayoutZoomLevelLimits()` ### Removed: `webFrame.setLayoutZoomLevelLimits()`
Chromium has removed support for changing the layout zoom level limits, and it Chromium has removed support for changing the layout zoom level limits, and it
is beyond Electron's capacity to maintain it. The function was deprecated in is beyond Electron's capacity to maintain it. The function was deprecated in
@ -68,7 +74,7 @@ Electron 8.x, and has been removed in Electron 9.x. The layout zoom level limits
are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
[here](https://chromium.googlesource.com/chromium/src/+/938b37a6d2886bf8335fc7db792f1eb46c65b2ae/third_party/blink/common/page/page_zoom.cc#11). [here](https://chromium.googlesource.com/chromium/src/+/938b37a6d2886bf8335fc7db792f1eb46c65b2ae/third_party/blink/common/page/page_zoom.cc#11).
### Sending non-JS objects over IPC now throws an exception ### Behavior Changed: Sending non-JS objects over IPC now throws an exception
In Electron 8.0, IPC was changed to use the Structured Clone Algorithm, In Electron 8.0, IPC was changed to use the Structured Clone Algorithm,
bringing significant performance improvements. To help ease the transition, the bringing significant performance improvements. To help ease the transition, the
@ -84,14 +90,14 @@ In Electron 9.0, the old serialization algorithm has been removed, and sending
such non-serializable objects will now throw an "object could not be cloned" such non-serializable objects will now throw an "object could not be cloned"
error. error.
### `shell.openItem` --> `shell.openPath` ### API Changed: `shell.openItem` is now `shell.openPath`
The `shell.openItem` API has been replaced with an asynchronous `shell.openPath` API. The `shell.openItem` API has been replaced with an asynchronous `shell.openPath` API.
You can see the original API proposal and reasoning [here](https://github.com/electron/governance/blob/master/wg-api/spec-documents/shell-openitem.md). You can see the original API proposal and reasoning [here](https://github.com/electron/governance/blob/master/wg-api/spec-documents/shell-openitem.md).
## Planned Breaking API Changes (8.0) ## Planned Breaking API Changes (8.0)
### Values sent over IPC are now serialized with Structured Clone Algorithm ### Behavior Changed: Values sent over IPC are now serialized with Structured Clone Algorithm
The algorithm used to serialize objects sent over IPC (through The algorithm used to serialize objects sent over IPC (through
`ipcRenderer.send`, `ipcRenderer.sendSync`, `WebContents.send` and related `ipcRenderer.send`, `ipcRenderer.sendSync`, `WebContents.send` and related
@ -142,7 +148,7 @@ these kinds of objects will throw a 'could not be cloned' error.
[SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm [SCA]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
### `<webview>.getWebContents()` ### Deprecated: `<webview>.getWebContents()`
This API is implemented using the `remote` module, which has both performance This API is implemented using the `remote` module, which has both performance
and security implications. Therefore its usage should be explicit. and security implications. Therefore its usage should be explicit.
@ -183,7 +189,7 @@ const { ipcRenderer } = require('electron')
ipcRenderer.invoke('openDevTools', webview.getWebContentsId()) ipcRenderer.invoke('openDevTools', webview.getWebContentsId())
``` ```
### `webFrame.setLayoutZoomLevelLimits()` ### Deprecated: `webFrame.setLayoutZoomLevelLimits()`
Chromium has removed support for changing the layout zoom level limits, and it Chromium has removed support for changing the layout zoom level limits, and it
is beyond Electron's capacity to maintain it. The function will emit a warning is beyond Electron's capacity to maintain it. The function will emit a warning
@ -193,7 +199,7 @@ limits are now fixed at a minimum of 0.25 and a maximum of 5.0, as defined
## Planned Breaking API Changes (7.0) ## Planned Breaking API Changes (7.0)
### Node Headers URL ### Deprecated: Atom.io Node Headers URL
This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url` This is the URL specified as `disturl` in a `.npmrc` file or as the `--dist-url`
command line flag when building native Node modules. Both will be supported for command line flag when building native Node modules. Both will be supported for
@ -203,7 +209,7 @@ Deprecated: https://atom.io/download/electron
Replace with: https://electronjs.org/headers Replace with: https://electronjs.org/headers
### `session.clearAuthCache(options)` ### API Changed: `session.clearAuthCache()` no longer accepts options
The `session.clearAuthCache` API no longer accepts options for what to clear, and instead unconditionally clears the whole cache. The `session.clearAuthCache` API no longer accepts options for what to clear, and instead unconditionally clears the whole cache.
@ -214,25 +220,25 @@ session.clearAuthCache({ type: 'password' })
session.clearAuthCache() session.clearAuthCache()
``` ```
### `powerMonitor.querySystemIdleState` ### API Changed: `powerMonitor.querySystemIdleState` is now `powerMonitor.getSystemIdleState`
```js ```js
// Removed in Electron 7.0 // Removed in Electron 7.0
powerMonitor.querySystemIdleState(threshold, callback) powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API // Replace with synchronous API
const idleState = getSystemIdleState(threshold) const idleState = powerMonitor.getSystemIdleState(threshold)
``` ```
### `powerMonitor.querySystemIdleTime` ### API Changed: `powerMonitor.querySystemIdleTime` is now `powerMonitor.getSystemIdleState`
```js ```js
// Removed in Electron 7.0 // Removed in Electron 7.0
powerMonitor.querySystemIdleTime(callback) powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API // Replace with synchronous API
const idleTime = getSystemIdleTime() const idleTime = powerMonitor.getSystemIdleTime()
``` ```
### webFrame Isolated World APIs ### API Changed: `webFrame.setIsolatedWorldInfo` replaces separate methods
```js ```js
// Removed in Electron 7.0 // Removed in Electron 7.0
@ -249,11 +255,11 @@ webFrame.setIsolatedWorldInfo(
}) })
``` ```
### Removal of deprecated `marked` property on getBlinkMemoryInfo ### Removed: `marked` property on `getBlinkMemoryInfo`
This property was removed in Chromium 77, and as such is no longer available. This property was removed in Chromium 77, and as such is no longer available.
### `webkitdirectory` attribute for `<input type="file"/>` ### Behavior Changed: `webkitdirectory` attribute for `<input type="file"/>` now lists directory contents
The `webkitdirectory` property on HTML file inputs allows them to select folders. The `webkitdirectory` property on HTML file inputs allows them to select folders.
Previous versions of Electron had an incorrect implementation where the `event.target.files` Previous versions of Electron had an incorrect implementation where the `event.target.files`
@ -286,9 +292,10 @@ In Electron 7, this now returns a `FileList` with a `File` object for:
Note that `webkitdirectory` no longer exposes the path to the selected folder. Note that `webkitdirectory` no longer exposes the path to the selected folder.
If you require the path to the selected folder rather than the folder contents, If you require the path to the selected folder rather than the folder contents,
see the `dialog.showOpenDialog` API ([link](https://github.com/electron/electron/blob/master/docs/api/dialog.md#dialogshowopendialogbrowserwindow-options)). see the `dialog.showOpenDialog` API ([link](https://github.com/electron/electron/blob/master/docs/api/dialog.md#dialogshowopendialogbrowserwindow-options)).
## Planned Breaking API Changes (6.0) ## Planned Breaking API Changes (6.0)
### `win.setMenu(null)` ### API Changed: `win.setMenu(null)` is now `win.removeMenu()`
```js ```js
// Deprecated // Deprecated
@ -297,7 +304,7 @@ win.setMenu(null)
win.removeMenu() win.removeMenu()
``` ```
### `contentTracing.getTraceBufferUsage()` ### API Changed: `contentTracing.getTraceBufferUsage()` is now a promise
```js ```js
// Deprecated // Deprecated
@ -310,7 +317,7 @@ contentTracing.getTraceBufferUsage().then(infoObject => {
}) })
``` ```
### `electron.screen` in renderer process ### API Changed: `electron.screen` in the renderer process should be accessed via `remote`
```js ```js
// Deprecated // Deprecated
@ -319,7 +326,7 @@ require('electron').screen
require('electron').remote.screen require('electron').remote.screen
``` ```
### `require` in sandboxed renderers ### API Changed: `require()`ing node builtins in sandboxed renderers no longer implicitly loads the `remote` version
```js ```js
// Deprecated // Deprecated
@ -343,25 +350,25 @@ require('path')
require('electron').remote.require('path') require('electron').remote.require('path')
``` ```
### `powerMonitor.querySystemIdleState` ### Deprecated: `powerMonitor.querySystemIdleState` replaced with `powerMonitor.getSystemIdleState`
```js ```js
// Deprecated // Deprecated
powerMonitor.querySystemIdleState(threshold, callback) powerMonitor.querySystemIdleState(threshold, callback)
// Replace with synchronous API // Replace with synchronous API
const idleState = getSystemIdleState(threshold) const idleState = powerMonitor.getSystemIdleState(threshold)
``` ```
### `powerMonitor.querySystemIdleTime` ### Deprecated: `powerMonitor.querySystemIdleTime` replaced with `powerMonitor.getSystemIdleTime`
```js ```js
// Deprecated // Deprecated
powerMonitor.querySystemIdleTime(callback) powerMonitor.querySystemIdleTime(callback)
// Replace with synchronous API // Replace with synchronous API
const idleTime = getSystemIdleTime() const idleTime = powerMonitor.getSystemIdleTime()
``` ```
### `app.enableMixedSandbox` ### Deprecated: `app.enableMixedSandbox()` is no longer needed
```js ```js
// Deprecated // Deprecated
@ -370,7 +377,7 @@ app.enableMixedSandbox()
Mixed-sandbox mode is now enabled by default. Mixed-sandbox mode is now enabled by default.
### `Tray` ### Deprecated: `Tray.setHighlightMode`
Under macOS Catalina our former Tray implementation breaks. Under macOS Catalina our former Tray implementation breaks.
Apple's native substitute doesn't support changing the highlighting behavior. Apple's native substitute doesn't support changing the highlighting behavior.
@ -383,7 +390,7 @@ tray.setHighlightMode(mode)
## Planned Breaking API Changes (5.0) ## Planned Breaking API Changes (5.0)
### `new BrowserWindow({ webPreferences })` ### Default Changed: `nodeIntegration` and `webviewTag` default to false, `contextIsolation` defaults to true
The following `webPreferences` option default values are deprecated in favor of the new defaults listed below. The following `webPreferences` option default values are deprecated in favor of the new defaults listed below.
@ -403,16 +410,16 @@ const w = new BrowserWindow({
}) })
``` ```
### `nativeWindowOpen` ### Behavior Changed: `nodeIntegration` in child windows opened via `nativeWindowOpen`
Child windows opened with the `nativeWindowOpen` option will always have Node.js integration disabled, unless `nodeIntegrationInSubFrames` is `true. Child windows opened with the `nativeWindowOpen` option will always have Node.js integration disabled, unless `nodeIntegrationInSubFrames` is `true`.
### Privileged Schemes Registration ### API Changed: Registering privileged schemes must now be done before app ready
Renderer process APIs `webFrame.setRegisterURLSchemeAsPrivileged` and `webFrame.registerURLSchemeAsBypassingCSP` as well as browser process API `protocol.registerStandardSchemes` have been removed. Renderer process APIs `webFrame.registerURLSchemeAsPrivileged` and `webFrame.registerURLSchemeAsBypassingCSP` as well as browser process API `protocol.registerStandardSchemes` have been removed.
A new API, `protocol.registerSchemesAsPrivileged` has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready. A new API, `protocol.registerSchemesAsPrivileged` has been added and should be used for registering custom schemes with the required privileges. Custom schemes are required to be registered before app ready.
### webFrame Isolated World APIs ### Deprecated: `webFrame.setIsolatedWorld*` replaced with `webFrame.setIsolatedWorldInfo`
```js ```js
// Deprecated // Deprecated
@ -429,7 +436,7 @@ webFrame.setIsolatedWorldInfo(
}) })
``` ```
## `webFrame.setSpellCheckProvider` ### API Changed: `webFrame.setSpellCheckProvider` now takes an asynchronous callback
The `spellCheck` callback is now asynchronous, and `autoCorrectWord` parameter has been removed. The `spellCheck` callback is now asynchronous, and `autoCorrectWord` parameter has been removed.
```js ```js
// Deprecated // Deprecated