docs: document what experimental means explicitly (#22893)

* docs: document what experimental means explicitly

* Apply suggestions from code review

Co-Authored-By: Jeremy Apthorp <jeremya@chromium.org>

* Update experimental.md

Co-authored-by: Jeremy Apthorp <jeremya@chromium.org>
This commit is contained in:
Samuel Attard 2020-04-02 09:32:18 -07:00 committed by GitHub
parent 429a2f4fe8
commit 22fb4f85e5
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
17 changed files with 40 additions and 17 deletions

View file

@ -1225,7 +1225,7 @@ stopAccessingSecurityScopedResource()
Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See [Apple's documentation](https://developer.apple.com/library/content/documentation/Security/Conceptual/AppSandboxDesignGuide/AppSandboxInDepth/AppSandboxInDepth.html#//apple_ref/doc/uid/TP40011183-CH3-SW16) for a description of how this system works.
### `app.enableSandbox()` _Experimental_
### `app.enableSandbox()`
Enables full sandbox mode on the app. This means that all renderers will be launched sandboxed, regardless of the value of the `sandbox` flag in WebPreferences.

View file

@ -1768,7 +1768,7 @@ Set a custom position for the traffic light buttons. Can only be used with `titl
Returns `Point` - The current position for the traffic light buttons. Can only be used with `titleBarStyle`
set to `hidden`.
#### `win.setTouchBar(touchBar)` _macOS_ _Experimental_
#### `win.setTouchBar(touchBar)` _macOS_
* `touchBar` TouchBar | null

View file

@ -26,7 +26,7 @@ The `Notification` class has the following static methods:
Returns `Boolean` - Whether or not desktop notifications are supported on the current system
### `new Notification([options])` _Experimental_
### `new Notification([options])`
* `options` Object (optional)
* `title` String - A title for the notification, which will be shown at the top of the notification window when it is shown.

View file

@ -54,7 +54,7 @@ only via IPC. The use of this option stops Electron from creating a Node.js runt
within this new window `window.open` follows the native behavior (by default Electron creates a [`BrowserWindow`](browser-window.md)
and returns a proxy to this via `window.open`).
[`app.enableSandbox`](app.md#appenablesandbox-experimental) can be used to force `sandbox: true` for all `BrowserWindow` instances.
[`app.enableSandbox`](app.md#appenablesandbox) can be used to force `sandbox: true` for all `BrowserWindow` instances.
```js
let win

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarButton(options)` _Experimental_
### `new TouchBarButton(options)`
* `options` Object
* `label` String (optional) - Button text.

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarColorPicker(options)` _Experimental_
### `new TouchBarColorPicker(options)`
* `options` Object
* `availableColors` String[] (optional) - Array of hex color strings to

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarGroup(options)` _Experimental_
### `new TouchBarGroup(options)`
* `options` Object
* `items` [TouchBar](touch-bar.md) - Items to display as a group.

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarLabel(options)` _Experimental_
### `new TouchBarLabel(options)`
* `options` Object
* `label` String (optional) - Text to display.

View file

@ -9,4 +9,4 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarOtherItemsProxy()` _Experimental_
### `new TouchBarOtherItemsProxy()`

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarPopover(options)` _Experimental_
### `new TouchBarPopover(options)`
* `options` Object
* `label` String (optional) - Popover button text.

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarScrubber(options)` _Experimental_
### `new TouchBarScrubber(options)`
* `options` Object
* `items` [ScrubberItem[]](structures/scrubber-item.md) - An array of items to place in this scrubber.

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarSegmentedControl(options)` _Experimental_
### `new TouchBarSegmentedControl(options)`
* `options` Object
* `segmentStyle` String (optional) - Style of the segments:

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarSlider(options)` _Experimental_
### `new TouchBarSlider(options)`
* `options` Object
* `label` String (optional) - Label text.

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBarSpacer(options)` _Experimental_
### `new TouchBarSpacer(options)`
* `options` Object
* `size` String (optional) - Size of spacer, possible values are:

View file

@ -4,7 +4,7 @@
Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes)
### `new TouchBar(options)` _Experimental_
### `new TouchBar(options)`
* `options` Object
* `items` ([TouchBarButton](touch-bar-button.md) | [TouchBarColorPicker](touch-bar-color-picker.md) | [TouchBarGroup](touch-bar-group.md) | [TouchBarLabel](touch-bar-label.md) | [TouchBarPopover](touch-bar-popover.md) | [TouchBarScrubber](touch-bar-scrubber.md) | [TouchBarSegmentedControl](touch-bar-segmented-control.md) | [TouchBarSlider](touch-bar-slider.md) | [TouchBarSpacer](touch-bar-spacer.md))[] (optional)

View file

@ -389,7 +389,7 @@ Calling `event.preventDefault` will prevent the page `keydown`/`keyup` events
and the menu shortcuts.
To only prevent the menu shortcuts, use
[`setIgnoreMenuShortcuts`](#contentssetignoremenushortcutsignore-experimental):
[`setIgnoreMenuShortcuts`](#contentssetignoremenushortcutsignore):
```javascript
const { BrowserWindow } = require('electron')
@ -1051,7 +1051,7 @@ or is rejected if the result of the code is a rejected promise.
Works like `executeJavaScript` but evaluates `scripts` in an isolated context.
#### `contents.setIgnoreMenuShortcuts(ignore)` _Experimental_
#### `contents.setIgnoreMenuShortcuts(ignore)`
* `ignore` Boolean

23
docs/experimental.md Normal file
View file

@ -0,0 +1,23 @@
# Experimental APIs
Some of Electrons APIs are tagged with `_Experimental_` in the documentation.
This tag indicates that the API may not be considered stable and the API may
be removed or modified more frequently than other APIs with less warning.
## Conditions for an API to be tagged as Experimental
Anyone can request an API be tagged as experimental in a feature PR, disagreements
on the experimental nature of a feature can be discussed in the API WG if they
can't be resolved in the PR.
## Process for removing the Experimental tag
Once an API has been stable and in at least two major stable release lines it
can be nominated to have its experimental tag removed. This discussion should
happen at an API WG meeting. Things to consider when discussing / nominating:
* The above "two major stables release lines" condition must have been met
* During that time no major bugs / issues should have been caused by the adoption of this feature
* The API is stable enough and hasn't been heavily impacted by Chromium upgrades
* Is anyone using the API?
* Is the API fulfilling the original proposed usecases, does it have any gaps?