From 22fb4f85e53581a6871d86e2f009ffad0772445a Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Thu, 2 Apr 2020 09:32:18 -0700 Subject: [PATCH] docs: document what experimental means explicitly (#22893) * docs: document what experimental means explicitly * Apply suggestions from code review Co-Authored-By: Jeremy Apthorp * Update experimental.md Co-authored-by: Jeremy Apthorp --- docs/api/app.md | 2 +- docs/api/browser-window.md | 2 +- docs/api/notification.md | 2 +- docs/api/sandbox-option.md | 2 +- docs/api/touch-bar-button.md | 2 +- docs/api/touch-bar-color-picker.md | 2 +- docs/api/touch-bar-group.md | 2 +- docs/api/touch-bar-label.md | 2 +- docs/api/touch-bar-other-items-proxy.md | 2 +- docs/api/touch-bar-popover.md | 2 +- docs/api/touch-bar-scrubber.md | 2 +- docs/api/touch-bar-segmented-control.md | 2 +- docs/api/touch-bar-slider.md | 2 +- docs/api/touch-bar-spacer.md | 2 +- docs/api/touch-bar.md | 2 +- docs/api/web-contents.md | 4 ++-- docs/experimental.md | 23 +++++++++++++++++++++++ 17 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 docs/experimental.md diff --git a/docs/api/app.md b/docs/api/app.md index 9026f40ac608..5ab4b7f9e64d 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -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. diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 4a68944109b9..ce51da2daee2 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -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 diff --git a/docs/api/notification.md b/docs/api/notification.md index 32a24a0d0fe9..7d3930c8afbc 100644 --- a/docs/api/notification.md +++ b/docs/api/notification.md @@ -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. diff --git a/docs/api/sandbox-option.md b/docs/api/sandbox-option.md index 8e856f73392c..fb8f889a5bcd 100644 --- a/docs/api/sandbox-option.md +++ b/docs/api/sandbox-option.md @@ -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 diff --git a/docs/api/touch-bar-button.md b/docs/api/touch-bar-button.md index 9945d8779c5a..df06d236d409 100644 --- a/docs/api/touch-bar-button.md +++ b/docs/api/touch-bar-button.md @@ -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. diff --git a/docs/api/touch-bar-color-picker.md b/docs/api/touch-bar-color-picker.md index b8dfcb7b5a37..5b44115ecf7c 100644 --- a/docs/api/touch-bar-color-picker.md +++ b/docs/api/touch-bar-color-picker.md @@ -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 diff --git a/docs/api/touch-bar-group.md b/docs/api/touch-bar-group.md index a4731e3da12a..a32e83dccaee 100644 --- a/docs/api/touch-bar-group.md +++ b/docs/api/touch-bar-group.md @@ -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. diff --git a/docs/api/touch-bar-label.md b/docs/api/touch-bar-label.md index 8159b0a1002f..6516f72e32c1 100644 --- a/docs/api/touch-bar-label.md +++ b/docs/api/touch-bar-label.md @@ -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. diff --git a/docs/api/touch-bar-other-items-proxy.md b/docs/api/touch-bar-other-items-proxy.md index a58b2ed6f308..ff94da55bd18 100644 --- a/docs/api/touch-bar-other-items-proxy.md +++ b/docs/api/touch-bar-other-items-proxy.md @@ -9,4 +9,4 @@ Process: [Main](../tutorial/application-architecture.md#main-and-renderer-processes) -### `new TouchBarOtherItemsProxy()` _Experimental_ +### `new TouchBarOtherItemsProxy()` diff --git a/docs/api/touch-bar-popover.md b/docs/api/touch-bar-popover.md index a6c73b9da097..a4195977cff2 100644 --- a/docs/api/touch-bar-popover.md +++ b/docs/api/touch-bar-popover.md @@ -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. diff --git a/docs/api/touch-bar-scrubber.md b/docs/api/touch-bar-scrubber.md index 00c9c8bfc0b5..4349e5162335 100644 --- a/docs/api/touch-bar-scrubber.md +++ b/docs/api/touch-bar-scrubber.md @@ -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. diff --git a/docs/api/touch-bar-segmented-control.md b/docs/api/touch-bar-segmented-control.md index a92de2a08e77..0622f1ce7a09 100644 --- a/docs/api/touch-bar-segmented-control.md +++ b/docs/api/touch-bar-segmented-control.md @@ -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: diff --git a/docs/api/touch-bar-slider.md b/docs/api/touch-bar-slider.md index 3f6c98fcd181..796322b4bc5f 100644 --- a/docs/api/touch-bar-slider.md +++ b/docs/api/touch-bar-slider.md @@ -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. diff --git a/docs/api/touch-bar-spacer.md b/docs/api/touch-bar-spacer.md index fb88289fc93a..65a19f4ffd34 100644 --- a/docs/api/touch-bar-spacer.md +++ b/docs/api/touch-bar-spacer.md @@ -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: diff --git a/docs/api/touch-bar.md b/docs/api/touch-bar.md index 79c575dab1f9..d2b97ecc63b5 100644 --- a/docs/api/touch-bar.md +++ b/docs/api/touch-bar.md @@ -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) diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md index 8f952590ba41..313d820d13f3 100644 --- a/docs/api/web-contents.md +++ b/docs/api/web-contents.md @@ -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 diff --git a/docs/experimental.md b/docs/experimental.md new file mode 100644 index 000000000000..b9bc620ea83a --- /dev/null +++ b/docs/experimental.md @@ -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?