docs: api history (#42982)

* feat(api-history): api history schema

Reference: https://github.com/electron/rfcs/blob/f36e0a8483e1ea844710890a8a7a1bd58ecbac05/text/0004-api-history-schema.md

* feat(api-history): add `lint:api-history` to `package.json`

* docs(api-history): add api history to `styleguide.md`

* docs(api-history): `win.flashFrame(flag)`

* docs(api-history): `new WebContentsView([options])`

* docs(api-history): non-navigation APIs on `WebContents`

* docs(api-history): `nativeImage.toDataURL`

* docs(api-history): `window.flashFrame(bool)`

* docs(api-history): `browser-view.md`

* docs(api-history): `ipcRenderer`

* docs(api-history): `protocol.*Protocol`

* revert: `new WebContentsView([options])`

This reverts commit 0a11efcf57cdf1f061ed4a3272e87f06d2fc7cb0.

* Apply suggestions from code review

Co-authored-by: David Sanders <[email protected]>

* fix(api-history): remove incorrect `pr-url`

Reference: https://github.com/electron/electron/pull/42982/files#r1692532877

* docs(api-history): schema word choice

Co-authored-by: Erick Zhao <[email protected]>

Reference: https://github.com/electron/website/commit/0b1b6a7cc0ed578a832f8ca254d1988c14f9bc13

* docs(api-history): nicer format example in `styleguide.md`

Reference: https://github.com/electron/electron/pull/42982#discussion_r1692539906

* docs(api-history): Always use double quotes for descriptions

* docs(api-history): `styleguide.md` improvements

* docs(api-history): copy `ipc-renderer.md` change to `context-bridge.md`

* docs(api-history): `styleguide.md` placement

* docs(api-history): add migration guide

* docs(api-history): remove confusing `breaking-changes-header` in `browser-view.md`

Reference: https://github.com/electron/electron/pull/42982/files/7b03c0703d7819add6afd022ec97a55b7a2aa268#r1703444772

* docs(api-history): move migration guide

Reference: https://github.com/electron/electron/pull/42982#discussion_r1703441001

* docs(api-history): update `breaking-changer-header`

Reference: https://github.com/electron/electron/pull/43217

* docs(api-history): deprecate `browser-view.md`

---------

Co-authored-by: David Sanders <[email protected]>

docs/api-history.schema.json

@@ -0,0 +1,47 @@
+{
+  "title": "JSON schema for API history blocks in Electron documentation",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$comment": "If you change this schema, remember to edit the TypeScript interfaces in the linting script.",
+  "definitions": {
+    "baseChangeSchema": {
+      "type": "object",
+      "properties": {
+        "pr-url": {
+          "description": "URL to the 'main' GitHub Pull Request for the change (i.e. not a backport PR)",
+          "type": "string", "pattern": "^https://github.com/electron/electron/pull/\\d+$",
+          "examples": [ "https://github.com/electron/electron/pull/26789" ]
+        },
+        "breaking-changes-header": {
+          "description": "Heading ID for the change in `electron/docs/breaking-changes.md`",
+          "type": "string", "minLength": 3,
+          "examples": [ "deprecated-browserwindowsettrafficlightpositionposition" ]
+        },
+        "description": {
+          "description": "Short description of the change",
+          "type": "string", "minLength": 3, "maxLength": 120,
+          "examples": [ "Made `trafficLightPosition` option work for `customButtonOnHover`." ]
+        }
+      },
+      "required": [ "pr-url" ],
+      "additionalProperties": false
+    },
+    "addedChangeSchema": {
+      "allOf": [ { "$ref": "#/definitions/baseChangeSchema" } ]
+    },
+    "deprecatedChangeSchema": {
+      "$comment": "TODO: Make 'breaking-changes-header' required in the future.",
+      "allOf": [ { "$ref": "#/definitions/baseChangeSchema" } ]
+    },
+    "changesChangeSchema": {
+      "$comment": "Unlike RFC, added `'type': 'object'` to appease AJV strict mode",
+      "allOf": [ { "$ref": "#/definitions/baseChangeSchema" }, { "type": "object", "required": [ "description" ] } ]
+    }
+  },
+  "type": "object",
+  "properties": {
+    "added": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/definitions/addedChangeSchema" } },
+    "deprecated": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/definitions/deprecatedChangeSchema" } },
+    "changes": { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/changesChangeSchema" } }
+  },
+  "additionalProperties": false
+}

docs/api/base-window.md

@@ -926,6 +926,17 @@ win.setSheetOffset(toolbarRect.height)
 
 #### `win.flashFrame(flag)`
 
+<!--
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/35658
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+-->
+
 * `flag` boolean
 
 Starts or stops flashing the window to attract user's attention.

docs/api/browser-view.md

@@ -1,5 +1,13 @@
 # BrowserView
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 > **Note**
 > The `BrowserView` class is deprecated, and replaced by the new
 > [`WebContentsView`](web-contents-view.md) class.
@@ -11,6 +19,14 @@ relative to its owning window. It is meant to be an alternative to the
 
 ## Class: BrowserView
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 > Create and control views.
 
 > **Note**
@@ -40,6 +56,14 @@ app.whenReady().then(() => {
 
 ### `new BrowserView([options])` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `options` Object (optional)
   * `webPreferences` [WebPreferences](structures/web-preferences.md?inline) (optional) - Settings of web page's features.
 
@@ -49,6 +73,14 @@ Objects created with `new BrowserView` have the following properties:
 
 #### `view.webContents` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 A [`WebContents`](web-contents.md) object owned by this view.
 
 ### Instance Methods
@@ -57,6 +89,18 @@ Objects created with `new BrowserView` have the following instance methods:
 
 #### `view.setAutoResize(options)` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    description: "Standardized auto-resizing behavior across all platforms"
+    breaking-changes-header: behavior-changed-browserviewsetautoresize-behavior-on-macos
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `options` Object
   * `width` boolean (optional) - If `true`, the view's width will grow and shrink together
     with the window. `false` by default.
@@ -69,18 +113,42 @@ Objects created with `new BrowserView` have the following instance methods:
 
 #### `view.setBounds(bounds)` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `bounds` [Rectangle](structures/rectangle.md)
 
 Resizes and moves the view to the supplied bounds relative to the window.
 
 #### `view.getBounds()` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 Returns [`Rectangle`](structures/rectangle.md)
 
 The `bounds` of this BrowserView instance as `Object`.
 
 #### `view.setBackgroundColor(color)` _Experimental_ _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/35658
+    breaking-changes-header: deprecated-browserview
+```
+-->
+
 * `color` string - Color in Hex, RGB, ARGB, HSL, HSLA or named CSS color format. The alpha channel is
   optional for the hex type.
 

docs/api/browser-window.md

@@ -1051,6 +1051,15 @@ win.setSheetOffset(toolbarRect.height)
 
 #### `win.flashFrame(flag)`
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41391
+    description: "`window.flashFrame(bool)` will flash dock icon continuously on macOS"
+    breaking-changes-header: behavior-changed-windowflashframebool-will-flash-dock-icon-continuously-on-macos
+```
+-->
+
 * `flag` boolean
 
 Starts or stops flashing the window to attract user's attention.

docs/api/context-bridge.md

@@ -1,5 +1,14 @@
 # contextBridge
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
 > Create a safe, bi-directional, synchronous bridge across isolated contexts
 
 Process: [Renderer](../glossary.md#renderer-process)

docs/api/ipc-renderer.md

@@ -7,6 +7,15 @@ hide_title: false
 
 # ipcRenderer
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
 > Communicate asynchronously from a renderer process to the main process.
 
 Process: [Renderer](../glossary.md#renderer-process)

docs/api/native-image.md

@@ -257,6 +257,15 @@ data.
 
 #### `image.toDataURL([options])`
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    description: "`nativeImage.toDataURL` will preserve PNG colorspace"
+    breaking-changes-header: behavior-changed-nativeimagetodataurl-will-preserve-png-colorspace
+```
+-->
+
 * `options` Object (optional)
   * `scaleFactor` Number (optional) - Defaults to 1.0.
 

docs/api/protocol.md

@@ -189,6 +189,15 @@ Returns `boolean` - Whether `scheme` is already handled.
 
 ### `protocol.registerFileProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -210,6 +219,15 @@ from protocols that follow the "generic URI syntax" like `file:`.
 
 ### `protocol.registerBufferProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -234,6 +252,15 @@ protocol.registerBufferProtocol('atom', (request, callback) => {
 
 ### `protocol.registerStringProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -250,6 +277,15 @@ property.
 
 ### `protocol.registerHttpProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -265,6 +301,15 @@ should be called with an object that has the `url` property.
 
 ### `protocol.registerStreamProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -314,6 +359,15 @@ protocol.registerStreamProtocol('atom', (request, callback) => {
 
 ### `protocol.unregisterProtocol(scheme)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 
 Returns `boolean` - Whether the protocol was successfully unregistered
@@ -322,12 +376,30 @@ Unregisters the custom protocol of `scheme`.
 
 ### `protocol.isProtocolRegistered(scheme)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 
 Returns `boolean` - Whether `scheme` is already registered.
 
 ### `protocol.interceptFileProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -341,6 +413,15 @@ which sends a file as a response.
 
 ### `protocol.interceptStringProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -354,6 +435,15 @@ which sends a `string` as a response.
 
 ### `protocol.interceptBufferProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -367,6 +457,15 @@ which sends a `Buffer` as a response.
 
 ### `protocol.interceptHttpProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -380,6 +479,15 @@ which sends a new HTTP request as a response.
 
 ### `protocol.interceptStreamProtocol(scheme, handler)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 * `handler` Function
   * `request` [ProtocolRequest](structures/protocol-request.md)
@@ -393,6 +501,15 @@ protocol handler.
 
 ### `protocol.uninterceptProtocol(scheme)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 
 Returns `boolean` - Whether the protocol was successfully unintercepted
@@ -401,6 +518,15 @@ Remove the interceptor installed for `scheme` and restore its original handler.
 
 ### `protocol.isProtocolIntercepted(scheme)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/36674
+    description: "`protocol.register*Protocol` and `protocol.intercept*Protocol` methods have been replaced with `protocol.handle`"
+    breaking-changes-header: deprecated-protocolunregisterinterceptbufferstringstreamfilehttpprotocol-and-protocolisprotocolregisteredintercepted
+```
+-->
+
 * `scheme` string
 
 Returns `boolean` - Whether `scheme` is already intercepted.

docs/api/web-contents.md

@@ -1126,18 +1126,42 @@ Reloads current page and ignores cache.
 
 #### `contents.canGoBack()` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Returns `boolean` - Whether the browser can go back to previous web page.
 
 **Deprecated:** Should use the new [`contents.navigationHistory.canGoBack`](navigation-history.md#navigationhistorycangoback) API.
 
 #### `contents.canGoForward()` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Returns `boolean` - Whether the browser can go forward to next web page.
 
 **Deprecated:** Should use the new [`contents.navigationHistory.canGoForward`](navigation-history.md#navigationhistorycangoforward) API.
 
 #### `contents.canGoToOffset(offset)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `offset` Integer
 
 Returns `boolean` - Whether the web page can go to `offset`.
@@ -1146,24 +1170,56 @@ Returns `boolean` - Whether the web page can go to `offset`.
 
 #### `contents.clearHistory()` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Clears the navigation history.
 
 **Deprecated:** Should use the new [`contents.navigationHistory.clear`](navigation-history.md#navigationhistoryclear) API.
 
 #### `contents.goBack()` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Makes the browser go back a web page.
 
 **Deprecated:** Should use the new [`contents.navigationHistory.goBack`](navigation-history.md#navigationhistorygoback) API.
 
 #### `contents.goForward()` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 Makes the browser go forward a web page.
 
 **Deprecated:** Should use the new [`contents.navigationHistory.goForward`](navigation-history.md#navigationhistorygoforward) API.
 
 #### `contents.goToIndex(index)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `index` Integer
 
 Navigates browser to the specified absolute web page index.
@@ -1172,6 +1228,14 @@ Navigates browser to the specified absolute web page index.
 
 #### `contents.goToOffset(offset)` _Deprecated_
 
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/41752
+    breaking-changes-header: deprecated-clearhistory-cangoback-goback-cangoforward-goforward-gotoindex-cangotooffset-gotooffset-on-webcontents
+```
+-->
+
 * `offset` Integer
 
 Navigates to the specified offset from the "current entry".
@@ -2148,6 +2212,15 @@ when the page becomes backgrounded. This also affects the Page Visibility API.
 
 #### `contents.setBackgroundThrottling(allowed)`
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/38924
+    description: "`WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`"
+    breaking-changes-header: behavior-changed-webcontentsbackgroundthrottling-set-to-false-affects-all-webcontents-in-the-host-browserwindow
+```
+-->
+
 * `allowed` boolean
 
 Controls whether or not this WebContents will throttle animations and timers
@@ -2258,6 +2331,15 @@ A [`Debugger`](debugger.md) instance for this webContents.
 
 #### `contents.backgroundThrottling`
 
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/38924
+    description: "`WebContents.backgroundThrottling` set to false affects all `WebContents` in the host `BrowserWindow`"
+    breaking-changes-header: behavior-changed-webcontentsbackgroundthrottling-set-to-false-affects-all-webcontents-in-the-host-browserwindow
+```
+-->
+
 A `boolean` property that determines whether or not this WebContents will throttle animations and timers
 when the page becomes backgrounded. This also affects the Page Visibility API.
 

docs/development/api-history-migration-guide.md

@@ -0,0 +1,190 @@
+# Electron API History Migration Guide
+
+This document demonstrates how to add API History blocks to existing APIs.
+
+## API history information
+
+Here are some resources you can use to find information on the history of an API:
+
+### Breaking Changes
+
+* [`breaking-changes.md`](../breaking-changes.md)
+
+### Additions
+
+* `git blame`
+* [Release notes](https://github.com/electron/electron/releases/)
+* [`electron-api-historian`](https://github.com/electron/electron-api-historian)
+
+## Example
+
+> [!NOTE]
+> The associated API is already removed, we will ignore that for the purpose of
+> this example.
+
+If we search through [`breaking-changes.md`](../breaking-changes.md) we can find
+[a function that was deprecated in Electron `25.0`](../breaking-changes.md#deprecated-browserwindowsettrafficlightpositionposition).
+
+```markdown
+<!-- docs/breaking-changes.md -->
+### Deprecated: `BrowserWindow.getTrafficLightPosition()`
+
+`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
+`BrowserWindow.getWindowButtonPosition()` API should be used instead
+which returns `null` instead of `{ x: 0, y: 0 }` when there is no custom
+position.
+
+<!-- docs/api/browser-window.md  -->
+#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+
+Returns `Point` - The custom position for the traffic light buttons in
+frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
+position.
+```
+
+We can then use `git blame` to find the Pull Request associated with that entry:
+
+```bash
+$ grep -n "BrowserWindow.getTrafficLightPosition" docs/breaking-changes.md 
+523:### Deprecated: `BrowserWindow.getTrafficLightPosition()`
+525:`BrowserWindow.getTrafficLightPosition()` has been deprecated, the
+
+$ git blame -L523,524 -- docs/breaking-changes.md
+1e206deec3e (Keeley Hammond 2023-04-06 21:23:29 -0700 523) ### Deprecated: `BrowserWindow.getTrafficLightPosition()`
+1e206deec3e (Keeley Hammond 2023-04-06 21:23:29 -0700 524)
+
+$ git log -1 1e206deec3e
+commit 1e206deec3ef142460c780307752a84782f9baed (tag: v26.0.0-nightly.20230407)
+Author: Keeley Hammond <[email protected]>
+Date:   Thu Apr 6 21:23:29 2023 -0700
+
+    docs: update E24/E25 breaking changes (#37878) <-- This is the associated Pull Request
+```
+
+Verify that the Pull Request is correct and make a corresponding entry in the
+API History:
+
+> [!NOTE]
+> Refer to the [API History section of `styleguide.md`](../styleguide.md#api-history)
+for information on how to create API History blocks.
+
+`````markdown
+#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+
+<!--
+```YAML history
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/37878
+    breaking-changes-header: deprecated-browserwindowgettrafficlightposition
+```
+-->
+
+Returns `Point` - The custom position for the traffic light buttons in
+frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
+position.
+`````
+
+You can keep looking through `breaking-changes.md` to find other breaking changes
+and add those in.
+
+You can also use [`git log -L :<funcname>:<file>`](https://git-scm.com/docs/git-log#Documentation/git-log.txt--Lltfuncnamegtltfilegt):
+
+```bash
+$ git log --reverse -L :GetTrafficLightPosition:shell/browser/native_window_mac.mm
+commit e01b1831d96d5d68f54af879b00c617358df5372
+Author: Cheng Zhao <[email protected]>
+Date:   Wed Dec 16 14:30:39 2020 +0900
+
+    feat: make trafficLightPosition work for customButtonOnHover (#26789)
+```
+
+Verify that the Pull Request is correct and make a corresponding entry in the
+API History:
+
+`````markdown
+#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+
+<!--
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/22533
+changes:
+  - pr-url: https://github.com/electron/electron/pull/26789
+    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
+    breaking-changes-header: behavior-changed-draggable-regions-on-macos
+```
+-->
+
+Returns `Point` - The custom position for the traffic light buttons in
+frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
+position.
+`````
+
+We will then look for when the API was originally added:
+
+```bash
+$ git log --reverse -L :GetTrafficLightPosition:shell/browser/native_window_mac.mm
+commit 3e2cec83d927b991855e21cc311ca9046e332601
+Author: Samuel Attard <[email protected]>
+Date:   Thu Mar 5 14:22:12 2020 -0800
+
+    feat: programmatically modify traffic light positioning (#22533)
+```
+
+Alternatively, you can use `git blame`:
+
+```bash
+$ git checkout 1e206deec3e^
+HEAD is now at e8c87859c4 fix: showAboutPanel also on linux (#37828)
+
+$ grep -n "getTrafficLightPosition" docs/api/browser-window.md
+1867:#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+
+$ git blame -L1867,1868 -- docs/api/browser-window.md
+0de1012280e (Cheng Zhao    2023-02-17 19:06:32 +0900 1867) #### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1868) 
+
+$ git checkout 0de1012280e^
+HEAD is now at 0a5e634736 test: rename & split internal module tests (#37318)
+
+$ grep -n "getTrafficLightPosition" docs/api/browser-window.md 
+1851:#### `win.getTrafficLightPosition()` _macOS_
+
+$ git blame -L1851,1852 -- docs/api/browser-window.md
+3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1851) #### `win.getTrafficLightPosition()` _macOS_
+3e2cec83d92 (Samuel Attard 2020-03-05 14:22:12 -0800 1852)
+
+$ git checkout 3e2cec83d92^
+HEAD is now at 1811751c6c docs: clean up dark mode related docs (#22489)
+
+$ grep -n "getTrafficLightPosition" docs/api/browser-window.md
+(Nothing)
+
+$ git checkout 3e2cec83d92
+HEAD is now at 3e2cec83d9 feat: programmatically modify traffic light positioning (#22533)
+```
+
+Verify that the Pull Request is correct and make a corresponding entry in the
+API History:
+
+`````markdown
+#### `win.getTrafficLightPosition()` _macOS_ _Deprecated_
+
+<!--
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/22533
+changes:
+  - pr-url: https://github.com/electron/electron/pull/26789
+    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
+    breaking-changes-header: behavior-changed-draggable-regions-on-macos
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/37878
+    breaking-changes-header: deprecated-browserwindowgettrafficlightposition
+```
+-->
+
+Returns `Point` - The custom position for the traffic light buttons in
+frameless window, `{ x: 0, y: 0 }` will be returned when there is no custom
+position.
+`````

docs/styleguide.md

@@ -250,6 +250,157 @@ The properties chapter must be in following form:
 The heading can be `###` or `####`-levels depending on whether the property
 belongs to a module or a class.
 
+## API History
+
+An "API History" block is a YAML code block encapsulated by an HTML comment that
+should be placed directly after the Markdown header for a class or method, like so:
+
+`````markdown
+#### `win.setTrafficLightPosition(position)` _macOS_
+
+<!--
+```YAML history
+added:
+  - pr-url: https://github.com/electron/electron/pull/22533
+changes:
+  - pr-url: https://github.com/electron/electron/pull/26789
+    description: "Made `trafficLightPosition` option work for `customButtonOnHover` window."
+deprecated:
+  - pr-url: https://github.com/electron/electron/pull/37094
+    breaking-changes-header: deprecated-browserwindowsettrafficlightpositionposition
+```
+-->
+
+* `position` [Point](structures/point.md)
+
+Set a custom position for the traffic light buttons. Can only be used with `titleBarStyle` set to `hidden`.
+`````
+
+It should adhere to the API History [JSON Schema](https://json-schema.org/)
+(`api-history.schema.json`) which you can find in the `docs` folder.
+The [API History Schema RFC][api-history-schema-rfc] includes example usage and detailed
+explanations for each aspect of the schema.
+
+The purpose of the API History block is to describe when/where/how/why an API was:
+
+* Added
+* Changed (usually breaking changes)
+* Deprecated
+
+Each API change listed in the block should include a link to the
+PR where that change was made along with an optional short description of the
+change. If applicable, include the [heading id](https://gist.github.com/asabaylus/3071099)
+for that change from the [breaking changes documentation](./breaking-changes.md).
+
+The [API History linting script][api-history-linting-script] (`lint:api-history`)
+validates API History blocks in the Electron documentation against the schema and
+performs some other checks. You can look at its [tests][api-history-tests] for more
+details.
+
+There are a few style guidelines that aren't covered by the linting script:
+
+### Format
+
+Always adhere to this format:
+
+  ```markdown
+  API HEADER                  |  #### `win.flashFrame(flag)`
+  BLANK LINE                  | 
+  HTML COMMENT OPENING TAG    |  <!--
+  API HISTORY OPENING TAG     |  ```YAML history
+  API HISTORY                 |  added:
+                              |    - pr-url: https://github.com/electron/electron/pull/22533
+  API HISTORY CLOSING TAG     |  ```
+  HTML COMMENT CLOSING TAG    |  -->
+  BLANK LINE                  |
+  ```
+
+### YAML
+
+* Use two spaces for indentation.
+* Do not use comments.
+
+### Descriptions
+
+* Always wrap descriptions with double quotation marks (i.e. "example").
+  * [Certain special characters (e.g. `[`, `]`) can break YAML parsing](https:/stackoverflow.com/a/37015689/19020549).
+* Describe the change in a way relevant to app developers and make it
+  capitalized, punctuated, and past tense.
+  * Refer to [Clerk](https://github.com/electron/clerk/blob/main/README.md#examples)
+    for examples.
+* Keep descriptions concise.
+  * Ideally, a description will match its corresponding header in the
+    breaking changes document.
+  * Favor using the release notes from the associated PR whenever possible.
+  * Developers can always view the breaking changes document or linked
+    pull request for more details.
+
+### Placement
+
+Generally, you should place the API History block directly after the Markdown header
+for a class or method that was changed. However, there are some instances where this
+is ambiguous:
+
+#### Chromium bump
+
+* [chore: bump chromium to 122.0.6194.0 (main)](https://github.com/electron/electron/pull/40750)
+  * [Behavior Changed: cross-origin iframes now use Permission Policy to access features][api-history-cross-origin]
+
+Sometimes a breaking change doesn't relate to any of the existing APIs. In this
+case, it is ok not to add API History anywhere.
+
+#### Change affecting multiple APIs
+
+* [refactor: ensure IpcRenderer is not bridgable](https://github.com/electron/electron/pull/40330)
+  * [Behavior Changed: ipcRenderer can no longer be sent over the contextBridge][api-history-ipc-renderer]
+
+Sometimes a breaking change involves multiple APIs. In this case, place the
+API History block under the top-level Markdown header for each of the
+involved APIs.
+
+`````markdown
+# contextBridge
+
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
+> Create a safe, bi-directional, synchronous bridge across isolated contexts
+`````
+
+`````markdown
+# ipcRenderer
+
+<!--
+```YAML history
+changes:
+  - pr-url: https://github.com/electron/electron/pull/40330
+    description: "`ipcRenderer` can no longer be sent over the `contextBridge`"
+    breaking-changes-header: behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge
+```
+-->
+
+Process: [Renderer](../glossary.md#renderer-process)
+`````
+
+Notice how an API History block wasn't added under:
+
+* `contextBridge.exposeInMainWorld(apiKey, api)`
+
+since that function wasn't changed, only how it may be used:
+
+```patch
+  contextBridge.exposeInMainWorld('app', {
+-   ipcRenderer,
++   onEvent: (cb) => ipcRenderer.on('foo', (e, ...args) => cb(args))
+  })
+```
+
 ## Documentation translations
 
 See [electron/i18n](https://github.com/electron/i18n#readme)
@@ -257,3 +408,8 @@ See [electron/i18n](https://github.com/electron/i18n#readme)
 [title-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case
 [sentence-case]: https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case
 [markdownlint]: https://github.com/DavidAnson/markdownlint
+[api-history-schema-rfc]: https://github.com/electron/rfcs/blob/f36e0a8483e1ea844710890a8a7a1bd58ecbac05/text/0004-api-history-schema.md
+[api-history-linting-script]: https://github.com/electron/lint-roller/blob/3030970136ec6b41028ef973f944d3e5cad68e1c/bin/lint-markdown-api-history.ts
+[api-history-tests]: https://github.com/electron/lint-roller/blob/main/tests/lint-roller-markdown-api-history.spec.ts
+[api-history-cross-origin]: https://github.com/electron/electron/blob/f508f6b6b570481a2b61d8c4f8c1951f492e4309/docs/breaking-changes.md#behavior-changed-cross-origin-iframes-now-use-permission-policy-to-access-features
+[api-history-ipc-renderer]: https://github.com/electron/electron/blob/f508f6b6b570481a2b61d8c4f8c1951f492e4309/docs/breaking-changes.md#behavior-changed-ipcrenderer-can-no-longer-be-sent-over-the-contextbridge

package.json

@@ -86,12 +86,13 @@
     "lint:objc": "node ./script/lint.js --objc",
     "lint:py": "node ./script/lint.js --py",
     "lint:gn": "node ./script/lint.js --gn",
-    "lint:docs": "remark docs -qf && npm run lint:js-in-markdown && npm run create-typescript-definitions && npm run lint:ts-check-js-in-markdown && npm run lint:docs-fiddles && npm run lint:docs-relative-links && npm run lint:markdown",
+    "lint:docs": "remark docs -qf && npm run lint:js-in-markdown && npm run create-typescript-definitions && npm run lint:ts-check-js-in-markdown && npm run lint:docs-fiddles && npm run lint:docs-relative-links && npm run lint:markdown && npm run lint:api-history",
     "lint:docs-fiddles": "standard \"docs/fiddles/**/*.js\"",
     "lint:docs-relative-links": "lint-roller-markdown-links --root docs \"**/*.md\"",
     "lint:markdown": "node ./script/lint.js --md",
     "lint:ts-check-js-in-markdown": "lint-roller-markdown-ts-check --root docs \"**/*.md\" --ignore \"breaking-changes.md\"",
     "lint:js-in-markdown": "lint-roller-markdown-standard --root docs \"**/*.md\"",
+    "lint:api-history": "lint-roller-markdown-api-history --root \"./docs/api/\" --schema \"./docs/api-history.schema.json\" --breaking-changes-file \"./docs/breaking-changes.md\" --check-placement --check-strings \"*.md\"",
     "create-api-json": "node script/create-api-json.js",
     "create-typescript-definitions": "npm run create-api-json && electron-typescript-definitions --api=electron-api.json && node spec/ts-smoke/runner.js",
     "gn-typescript-definitions": "npm run create-typescript-definitions && shx cp electron.d.ts",