docs: document modernization initiative more clearly (#17376)

* docs: document modernization initiative more clearly
electron · Mar 19, 2019 · 879462a · 879462a
1 parent 53f4af7
commit 879462a
Show file tree

Hide file tree

Showing 18 changed files with 102 additions and 34 deletions.
diff --git a/docs/api/app.md b/docs/api/app.md
@@ -623,7 +623,7 @@ On _Windows_, there are 2 kinds of icons:
 
 On _Linux_ and _macOS_, icons depend on the application associated with file mime type.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `app.getFileIcon(path[, options])`
 

diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
@@ -1230,7 +1230,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
 be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
 that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `win.capturePage([rect])`
 

diff --git a/docs/api/content-tracing.md b/docs/api/content-tracing.md
@@ -46,7 +46,7 @@ Get a set of category groups. The category groups can change as new code paths a
 
 Once all child processes have acknowledged the `getCategories` request the `callback` is invoked with an array of category groups.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `contentTracing.getCategories()`
 
@@ -66,7 +66,7 @@ Recording begins immediately locally and asynchronously on child processes
 as soon as they receive the EnableRecording request. The `callback` will be
 called once all child processes have acknowledged the `startRecording` request.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `contentTracing.startRecording(options)`
 
@@ -100,7 +100,7 @@ Trace data will be written into `resultFilePath` if it is not empty or into a
 temporary file. The actual file path will be passed to `callback` if it's not
 `null`.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `contentTracing.stopRecording(resultFilePath)`
 
@@ -130,7 +130,7 @@ Get the maximum usage across processes of trace buffer as a percentage of the
 full state. When the TraceBufferUsage value is determined the `callback` is
 called.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `contentTracing.getTraceBufferUsage()`
 

diff --git a/docs/api/cookies.md b/docs/api/cookies.md
@@ -99,7 +99,7 @@ the response.
 Sends a request to get all cookies matching `filter`, `callback` will be called
 with `callback(error, cookies)` on complete.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `cookies.set(details)`
 
@@ -142,7 +142,7 @@ Sets a cookie with `details`.
 Sets a cookie with `details`, `callback` will be called with `callback(error)`
 on complete.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `cookies.remove(url, name)`
 
@@ -162,7 +162,7 @@ Removes the cookies matching `url` and `name`
 Removes the cookies matching `url` and `name`, `callback` will called with
 `callback()` on complete.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `cookies.flushStore()`
 
@@ -176,4 +176,4 @@ Writes any unwritten cookies data to disk.
 
 Writes any unwritten cookies data to disk.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
diff --git a/docs/api/debugger.md b/docs/api/debugger.md
@@ -60,7 +60,7 @@ Detaches the debugger from the `webContents`.
 
 Send given command to the debugging target.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `debugger.sendCommand(method[, commandParams])`
 

diff --git a/docs/api/desktop-capturer.md b/docs/api/desktop-capturer.md
@@ -101,7 +101,7 @@ captured.
 
 [`navigator.mediaDevices.getUserMedia`]: https://developer.mozilla.org/en/docs/Web/API/MediaDevices/getUserMedia
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `desktopCapturer.getSources(options)`
 

diff --git a/docs/api/dialog.md b/docs/api/dialog.md
@@ -335,7 +335,7 @@ On Windows the options are more limited, due to the Win32 APIs used:
 * The `browserWindow` argument is ignored since it is not possible to make
    this confirmation dialog modal.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `dialog.showCertificateTrustDialog([browserWindow, ]options)` _macOS_ _Windows_
 

diff --git a/docs/api/in-app-purchase.md b/docs/api/in-app-purchase.md
@@ -30,7 +30,7 @@ The `inAppPurchase` module has the following methods:
 
 You should listen for the `transactions-updated` event as soon as possible and certainly before you call `purchaseProduct`.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `inAppPurchase.purchaseProduct(productID, quantity)`
 
@@ -49,7 +49,7 @@ You should listen for the `transactions-updated` event as soon as possible and c
 
 Retrieves the product descriptions.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `inAppPurchase.getProducts(productIDs)`
 

diff --git a/docs/api/modernization/overview.md b/docs/api/modernization/overview.md
@@ -0,0 +1,10 @@
+## Modernization
+
+The Electron team is currently undergoing an initiative to modernize our API in a few concrete ways. These include: updating our modules to use idiomatic JS properties instead of separate `getPropertyX` and `setpropertyX`, converting callbacks to promises, and removing some other anti-patterns present in our APIs. The current status of the Promise intiative can be tracked in the [promisification](promisification.md) tracking file.
+
+As we work to perform these updates, we seek to create the least disruptive amount of change at any given time, so as many changes as possible will be introduced in a backward compatible manner and deprecated after enough time has passed to give users a chance to upgrade their API calls.
+
+This document and its child documents will be updated to reflect the latest status of our API changes.
+
+* [Promisification](promisification.md)
+* [Property Updates](property-updates.md)
diff --git a/docs/api/promisification.md → docs/api/modernization/promisification.md b/docs/api/promisification.md → docs/api/modernization/promisification.md
diff --git a/docs/api/modernization/property-updates.md b/docs/api/modernization/property-updates.md
@@ -0,0 +1,58 @@
+## Property Updates
+
+The Electron team is currently undergoing an initiative to convert separate getter and setter functions in Electron to bespoke properties with `get` and `set` functionality. During this transition period, both the new properties and old getters and setters of these functions will work correctly and be documented.
+
+## Candidates
+
+* `app` module
+  * `accessibilitySupport`
+  * `badgeCount`
+  * `applicationMenu`
+  * `name`
+  * `dock`
+    * `badge`
+* `autoUpdater` module
+  * `feedUrl`
+* `BrowserWindow`
+  * `fullscreen`
+  * `simpleFullscreen`
+  * `movable`
+  * `resizable`
+  * `maximizable`
+  * `minimizable`
+  * `fullscreenable`
+  * `closable`
+  * `alwaysOnTop`
+  * `title`
+  * `documentEdited`
+  * `hasShadow`
+  * `autohideMenuBar`
+  * `menubarVisible`
+  * `visibleOnAllWorkspaces`
+* `crashReporter` module
+  * `uploadToServer`
+* `DownloadItem` class
+  * `savePath`
+  * `paused`
+* `NativeImage`
+  * `templateImage`
+* `Session` module
+  * `preloads`
+* `SystemPreferences` module
+  * `appLevelAppearance`
+* `webContents` module
+  * `zoomFactor`
+  * `zoomLevel`
+  * `audioMuted`
+  * `userAgent`
+  * `frameRate`
+* `webFrame` modules
+  * `zoomFactor`
+  * `zoomLevel`
+  * `audioMuted`
+* `<webview>`
+  * `zoomFactor`
+  * `zoomLevel`
+  * `audioMuted`
+
+## Converted Properties
diff --git a/docs/api/net-log.md b/docs/api/net-log.md
@@ -35,7 +35,7 @@ Starts recording network events to `path`.
 
 Stops recording network events. If not called, net logging will automatically end when app quits.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `netLog.stopLogging()`
 

diff --git a/docs/api/protocol.md b/docs/api/protocol.md
@@ -292,7 +292,7 @@ Unregisters the custom protocol of `scheme`.
 The `callback` will be called with a boolean that indicates whether there is
 already a handler for `scheme`.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `protocol.isProtocolHandled(scheme)`
 

diff --git a/docs/api/session.md b/docs/api/session.md
@@ -101,7 +101,7 @@ The following methods are available on instances of `Session`:
 
 Callback is invoked with the session's current cache size.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.getCacheSize()`
 
@@ -114,7 +114,7 @@ Returns `Promise<Integer>` - the session's current cache size, in bytes.
 
 Clears the session’s HTTP cache.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.clearCache()`
 
@@ -136,7 +136,7 @@ Clears the session’s HTTP cache.
 
 Clears the storage data for the current session.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.clearStorageData([options])`
 
@@ -231,7 +231,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
    Match local addresses. The meaning of `<local>` is whether the
    host matches one of: "127.0.0.1", "::1", "localhost".
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.setProxy(config)`
 
@@ -319,7 +319,7 @@ The `proxyBypassRules` is a comma separated list of rules described below:
 Resolves the proxy information for `url`. The `callback` will be called with
 `callback(proxy)` when the request is performed.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.resolveProxy(url)`
 
@@ -463,7 +463,7 @@ session.fromPartition('some-partition').setPermissionCheckHandler((webContents,
 
 Clears the host resolver cache.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.clearHostResolverCache()`
 
@@ -512,7 +512,7 @@ Returns `String` - The user agent for this session.
 * `callback` Function
   * `result` Buffer - Blob data.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.getBlobData(identifier)`
 
@@ -546,7 +546,7 @@ the initial state will be `interrupted`. The download will start only when the
 
 Clears the session’s HTTP authentication cache.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `ses.clearAuthCache(options)`
 

diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
@@ -980,7 +980,7 @@ contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1"
   })
 ```
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `contents.executeJavaScript(code[, userGesture])`
 
@@ -1179,7 +1179,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
 be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
 that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `contents.capturePage([rect])`
 
@@ -1235,7 +1235,7 @@ settings.
 The `callback` will be called with `callback(error, data)` on completion. The
 `data` is a `Buffer` that contains the generated PDF data.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 #### `contents.printToPDF(options)`
 

diff --git a/docs/api/web-frame.md b/docs/api/web-frame.md
@@ -123,7 +123,7 @@ In the browser window some HTML APIs like `requestFullScreen` can only be
 invoked by a gesture from the user. Setting `userGesture` to `true` will remove
 this limitation.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `webFrame.executeJavaScript(code[, userGesture])`
 
@@ -152,7 +152,7 @@ or is rejected if the result of the code is a rejected promise.
 
 Works like `executeJavaScript` but evaluates `scripts` in an isolated context.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])`
 

diff --git a/docs/api/webview-tag.md b/docs/api/webview-tag.md
@@ -392,7 +392,7 @@ Evaluates `code` in page. If `userGesture` is set, it will create the user
 gesture context in the page. HTML APIs like `requestFullScreen`, which require
 user action, can take advantage of this option for automation.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `<webview>.executeJavaScript(code[, userGesture])`
 
@@ -563,7 +563,7 @@ Prints `webview`'s web page. Same as `webContents.print([options])`.
 
 Prints `webview`'s web page as PDF, Same as `webContents.printToPDF(options, callback)`.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `<webview>.printToPDF(options)`
 
@@ -591,7 +591,7 @@ Captures a snapshot of the page within `rect`. Upon completion `callback` will
 be called with `callback(image)`. The `image` is an instance of [NativeImage](native-image.md)
 that stores data of the snapshot. Omitting `rect` will capture the whole visible page.
 
-**[Deprecated Soon](promisification.md)**
+**[Deprecated Soon](modernization/promisification.md)**
 
 ### `<webview>.capturePage([rect])`
 

diff --git a/filenames.auto.gni b/filenames.auto.gni
@@ -29,14 +29,14 @@ auto_filenames = {
     "docs/api/locales.md",
     "docs/api/menu-item.md",
     "docs/api/menu.md",
+    "docs/api/modernization",
     "docs/api/native-image.md",
     "docs/api/net-log.md",
     "docs/api/net.md",
     "docs/api/notification.md",
     "docs/api/power-monitor.md",
     "docs/api/power-save-blocker.md",
     "docs/api/process.md",
-    "docs/api/promisification.md",
     "docs/api/protocol.md",
     "docs/api/remote.md",
     "docs/api/sandbox-option.md",