From 2223cacd5b788c475b040090ebf08e45a71ac8f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Sat, 8 Sep 2018 11:40:05 +0200 Subject: [PATCH 1/5] tools: fix doc tool behavior for version arrays Even though the doc tool supports version arrays in theory, it fails to sort them properly causing the tool to crash. --- tools/doc/common.js | 2 +- tools/doc/html.js | 14 +++++++++++--- 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/tools/doc/common.js b/tools/doc/common.js index 7d8aefb65d84fd..86daae6cfc6d56 100644 --- a/tools/doc/common.js +++ b/tools/doc/common.js @@ -43,4 +43,4 @@ function extractAndParseYAML(text) { return meta; } -module.exports = { isYAMLBlock, extractAndParseYAML }; +module.exports = { arrify, isYAMLBlock, extractAndParseYAML }; diff --git a/tools/doc/html.js b/tools/doc/html.js index 5babe1c97e679a..7ae818b7a2567c 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -308,7 +308,9 @@ function parseYAML(text) { .use(htmlStringify) .processSync(change.description).toString(); - result += `${change.version}\n` + + const version = common.arrify(change.version).join(', '); + + result += `${version}\n` + `${description}\n`; }); @@ -326,10 +328,16 @@ function parseYAML(text) { return result; } +function minVersion(a) { + if (!Array.isArray(a)) + return a; + return a.reduce((min, e) => !min || versionSort(min, e) < 0 ? e : min); +} + const numberRe = /^\d*/; function versionSort(a, b) { - a = a.trim(); - b = b.trim(); + a = minVersion(a).trim(); + b = minVersion(b).trim(); let i = 0; // Common prefix length. while (i < a.length && i < b.length && a[i] === b[i]) i++; a = a.substr(i); From 31db45f84efd29a6134017ed2c6e8b4d5edd77fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Sat, 8 Sep 2018 11:44:11 +0200 Subject: [PATCH 2/5] doc: add full deprecation history I tried to manually reconstruct the history of deprecations and to track them down to their origins. Having these documented publicly makes it much easier to find out when deprecations were introduced or changed. --- doc/api/deprecations.md | 1110 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 1110 insertions(+) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 5a7f9d08a15e5f..661db7394033f8 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -40,6 +40,17 @@ However, the deprecation identifier will not be modified. ### DEP0001: http.OutgoingMessage.prototype.flush + Type: Runtime @@ -48,6 +59,18 @@ The `OutgoingMessage.prototype.flush()` method is deprecated. Use ### DEP0002: require('\_linklist') + Type: End-of-Life @@ -55,6 +78,17 @@ The `_linklist` module is deprecated. Please use a userland alternative. ### DEP0003: \_writableState.buffer + Type: Runtime @@ -63,6 +97,20 @@ The `_writableState.buffer` property is deprecated. Use the ### DEP0004: CryptoStream.prototype.readyState + Type: End-of-Life @@ -70,6 +118,18 @@ The `CryptoStream.prototype.readyState` property was removed. ### DEP0005: Buffer() constructor + Type: Runtime (supports [`--pending-deprecation`][]) @@ -98,6 +158,18 @@ outside `node_modules` in order to better target developers, rather than users. ### DEP0006: child\_process options.customFds + Type: Runtime @@ -107,6 +179,21 @@ option should be used instead. ### DEP0007: Replace cluster worker.suicide with worker.exitedAfterDisconnect + Type: End-of-Life @@ -119,6 +206,15 @@ precisely describe the actual semantics and was unnecessarily emotion-laden. ### DEP0008: require('constants') + Type: Documentation-only @@ -129,6 +225,18 @@ to the `constants` property exposed by the relevant module. For instance, ### DEP0009: crypto.pbkdf2 without digest + Type: End-of-Life @@ -140,6 +248,20 @@ undefined `digest` will throw a `TypeError`. ### DEP0010: crypto.createCredentials + Type: End-of-Life @@ -148,6 +270,20 @@ The `crypto.createCredentials()` API was removed. Please use ### DEP0011: crypto.Credentials + Type: End-of-Life @@ -156,6 +292,20 @@ instead. ### DEP0012: Domain.dispose + Type: End-of-Life @@ -164,6 +314,15 @@ explicitly via error event handlers set on the domain instead. ### DEP0013: fs asynchronous function without callback + Type: End-of-Life @@ -172,6 +331,23 @@ in Node.js 10.0.0 onwards. (See https://github.com/nodejs/node/pull/12562.) ### DEP0014: fs.read legacy String interface + Type: End-of-Life @@ -180,6 +356,23 @@ API as mentioned in the documentation instead. ### DEP0015: fs.readSync legacy String interface + Type: End-of-Life @@ -188,6 +381,15 @@ The [`fs.readSync()`][] legacy `String` interface is deprecated. Use the ### DEP0016: GLOBAL/root + Type: Runtime @@ -196,6 +398,15 @@ and should no longer be used. ### DEP0017: Intl.v8BreakIterator + Type: End-of-Life @@ -204,6 +415,12 @@ See [`Intl.Segmenter`](https://github.com/tc39/proposal-intl-segmenter). ### DEP0018: Unhandled promise rejections + Type: Runtime @@ -213,6 +430,17 @@ code. ### DEP0019: require('.') resolved outside directory + Type: Runtime @@ -222,6 +450,17 @@ release. ### DEP0020: Server.connections + Type: Runtime @@ -230,6 +469,17 @@ The [`Server.connections`][] property is deprecated. Please use the ### DEP0021: Server.listenFD + Type: Runtime @@ -238,6 +488,12 @@ The `Server.listenFD()` method is deprecated. Please use ### DEP0022: os.tmpDir() + Type: Runtime @@ -245,6 +501,17 @@ The `os.tmpDir()` API is deprecated. Please use [`os.tmpdir()`][] instead. ### DEP0023: os.getNetworkInterfaces() + Type: Runtime @@ -253,6 +520,15 @@ The `os.getNetworkInterfaces()` method is deprecated. Please use the ### DEP0024: REPLServer.prototype.convertToContext() + Type: End-of-Life @@ -260,6 +536,17 @@ The `REPLServer.prototype.convertToContext()` API has been removed. ### DEP0025: require('sys') + Type: Runtime @@ -267,6 +554,17 @@ The `sys` module is deprecated. Please use the [`util`][] module instead. ### DEP0026: util.print() + Type: Runtime @@ -275,6 +573,17 @@ instead. ### DEP0027: util.puts() + Type: Runtime @@ -282,6 +591,17 @@ The [`util.puts()`][] API is deprecated. Please use [`console.log()`][] instead. ### DEP0028: util.debug() + Type: Runtime @@ -290,6 +610,17 @@ instead. ### DEP0029: util.error() + Type: Runtime @@ -298,6 +629,15 @@ instead. ### DEP0030: SlowBuffer + Type: Documentation-only @@ -306,6 +646,15 @@ The [`SlowBuffer`][] class is deprecated. Please use ### DEP0031: ecdh.setPublicKey() + Type: Documentation-only @@ -314,6 +663,17 @@ API is not useful. ### DEP0032: domain module + Type: Documentation-only @@ -321,6 +681,17 @@ The [`domain`][] module is deprecated and should not be used. ### DEP0033: EventEmitter.listenerCount() + Type: Documentation-only @@ -329,6 +700,17 @@ deprecated. Please use [`emitter.listenerCount(eventName)`][] instead. ### DEP0034: fs.exists(path, callback) + Type: Documentation-only @@ -337,6 +719,16 @@ The [`fs.exists(path, callback)`][] API is deprecated. Please use ### DEP0035: fs.lchmod(path, mode, callback) + Type: Documentation-only @@ -344,13 +736,74 @@ The [`fs.lchmod(path, mode, callback)`][] API is deprecated. ### DEP0036: fs.lchmodSync(path, mode) + Type: Documentation-only The [`fs.lchmodSync(path, mode)`][] API is deprecated. + +### DEP0037: fs.lchown(path, uid, gid, callback) + + +Type: Deprecation revoked + +The [`fs.lchown(path, uid, gid, callback)`][] API is deprecated. + + +### DEP0038: fs.lchownSync(path, uid, gid) + + +Type: Deprecation revoked + +The [`fs.lchownSync(path, uid, gid)`][] API is deprecated. + ### DEP0039: require.extensions + Type: Documentation-only @@ -358,6 +811,12 @@ The [`require.extensions`][] property is deprecated. ### DEP0040: punycode module + Type: Documentation-only @@ -366,6 +825,20 @@ instead. ### DEP0041: NODE\_REPL\_HISTORY\_FILE environment variable + Type: End-of-Life @@ -374,6 +847,20 @@ The `NODE_REPL_HISTORY_FILE` environment variable was removed. Please use ### DEP0042: tls.CryptoStream + Type: End-of-Life @@ -382,6 +869,16 @@ The [`tls.CryptoStream`][] class was removed. Please use ### DEP0043: tls.SecurePair + Type: Documentation-only @@ -390,6 +887,19 @@ The [`tls.SecurePair`][] class is deprecated. Please use ### DEP0044: util.isArray() + Type: Documentation-only @@ -398,6 +908,19 @@ instead. ### DEP0045: util.isBoolean() + Type: Documentation-only @@ -405,6 +928,19 @@ The [`util.isBoolean()`][] API is deprecated. ### DEP0046: util.isBuffer() + Type: Documentation-only @@ -413,6 +949,19 @@ The [`util.isBuffer()`][] API is deprecated. Please use ### DEP0047: util.isDate() + Type: Documentation-only @@ -420,6 +969,19 @@ The [`util.isDate()`][] API is deprecated. ### DEP0048: util.isError() + Type: Documentation-only @@ -427,6 +989,19 @@ The [`util.isError()`][] API is deprecated. ### DEP0049: util.isFunction() + Type: Documentation-only @@ -434,6 +1009,19 @@ The [`util.isFunction()`][] API is deprecated. ### DEP0050: util.isNull() + Type: Documentation-only @@ -441,6 +1029,19 @@ The [`util.isNull()`][] API is deprecated. ### DEP0051: util.isNullOrUndefined() + Type: Documentation-only @@ -448,6 +1049,19 @@ The [`util.isNullOrUndefined()`][] API is deprecated. ### DEP0052: util.isNumber() + Type: Documentation-only @@ -455,6 +1069,19 @@ The [`util.isNumber()`][] API is deprecated. ### DEP0053 util.isObject() + Type: Documentation-only @@ -462,6 +1089,19 @@ The [`util.isObject()`][] API is deprecated. ### DEP0054: util.isPrimitive() + Type: Documentation-only @@ -469,6 +1109,19 @@ The [`util.isPrimitive()`][] API is deprecated. ### DEP0055: util.isRegExp() + Type: Documentation-only @@ -476,6 +1129,19 @@ The [`util.isRegExp()`][] API is deprecated. ### DEP0056: util.isString() + Type: Documentation-only @@ -483,6 +1149,19 @@ The [`util.isString()`][] API is deprecated. ### DEP0057: util.isSymbol() + Type: Documentation-only @@ -490,6 +1169,19 @@ The [`util.isSymbol()`][] API is deprecated. ### DEP0058: util.isUndefined() + Type: Documentation-only @@ -497,6 +1189,15 @@ The [`util.isUndefined()`][] API is deprecated. ### DEP0059: util.log() + Type: Documentation-only @@ -504,6 +1205,15 @@ The [`util.log()`][] API is deprecated. ### DEP0060: util.\_extend() + Type: Documentation-only @@ -511,6 +1221,18 @@ The [`util._extend()`][] API is deprecated. ### DEP0061: fs.SyncWriteStream + Type: End-of-Life @@ -520,6 +1242,12 @@ alternative. ### DEP0062: node --debug + Type: Runtime @@ -529,6 +1257,12 @@ instead. ### DEP0063: ServerResponse.prototype.writeHeader() + Type: Documentation-only @@ -540,6 +1274,20 @@ officially supported API. ### DEP0064: tls.createSecurePair() + Type: Runtime @@ -548,6 +1296,15 @@ The `tls.createSecurePair()` API was deprecated in documentation in Node.js ### DEP0065: repl.REPL_MODE_MAGIC and NODE_REPL_MODE=magic + Type: End-of-Life @@ -562,6 +1319,12 @@ removed. Please use `sloppy` instead. ### DEP0066: outgoingMessage.\_headers, outgoingMessage.\_headerNames + Type: Documentation-only @@ -577,6 +1340,12 @@ were never documented as officially supported properties. ### DEP0067: OutgoingMessage.prototype.\_renderHeaders + Type: Documentation-only @@ -588,6 +1357,12 @@ an officially supported API. ### DEP0068: node debug + Type: Runtime @@ -596,6 +1371,18 @@ a V8-inspector based CLI debugger available through `node inspect`. ### DEP0069: vm.runInDebugContext(string) + Type: End-of-Life @@ -605,6 +1392,15 @@ DebugContext was an experimental API. ### DEP0070: async_hooks.currentId() + Type: End-of-Life @@ -615,6 +1411,15 @@ This change was made while `async_hooks` was an experimental API. ### DEP0071: async_hooks.triggerId() + Type: End-of-Life @@ -625,6 +1430,15 @@ This change was made while `async_hooks` was an experimental API. ### DEP0072: async_hooks.AsyncResource.triggerId() + Type: End-of-Life @@ -635,6 +1449,15 @@ This change was made while `async_hooks` was an experimental API. ### DEP0073: Several internal properties of net.Server + Type: End-of-Life @@ -646,6 +1469,12 @@ code, no replacement API is provided. ### DEP0074: REPLServer.bufferedCommand + Type: Runtime @@ -654,6 +1483,12 @@ The `REPLServer.bufferedCommand` property was deprecated in favor of ### DEP0075: REPLServer.parseREPLKeyword() + Type: Runtime @@ -661,6 +1496,15 @@ Type: Runtime ### DEP0076: tls.parseCertString() + Type: Runtime @@ -684,6 +1528,12 @@ difference is that `querystring.parse()` does url decoding: ### DEP0077: Module.\_debug() + Type: Runtime @@ -694,6 +1544,12 @@ supported API. ### DEP0078: REPLServer.turnOffEditorMode() + Type: Runtime @@ -701,6 +1557,18 @@ Type: Runtime ### DEP0079: Custom inspection function on Objects via .inspect() + Type: End-of-Life @@ -711,6 +1579,12 @@ may be specified. ### DEP0080: path.\_makeLong() + Type: Documentation-only @@ -720,6 +1594,12 @@ and replaced with an identical, public `path.toNamespacedPath()` method. ### DEP0081: fs.truncate() using a file descriptor + Type: Runtime @@ -729,6 +1609,12 @@ file descriptors. ### DEP0082: REPLServer.prototype.memory() + Type: Runtime @@ -737,6 +1623,12 @@ the `REPLServer` itself. Do not use this function. ### DEP0083: Disabling ECDH by setting ecdhCurve to false + Type: Runtime @@ -747,6 +1639,12 @@ the client. Use the `ciphers` parameter instead. ### DEP0084: requiring bundled internal dependencies + Type: Runtime @@ -778,6 +1676,17 @@ code modification is necessary if that is done. ### DEP0085: AsyncHooks Sensitive API + Type: End-of-Life @@ -787,6 +1696,17 @@ API instead. ### DEP0086: Remove runInAsyncIdScope + Type: End-of-Life @@ -796,6 +1716,14 @@ details. ### DEP0089: require('assert') + Type: Documentation-only @@ -805,6 +1733,15 @@ same as the legacy assert but it will always use strict equality checks. ### DEP0090: Invalid GCM authentication tag lengths + Type: End-of-Life @@ -816,6 +1753,12 @@ considered invalid in compliance with [NIST SP 800-38D][]. ### DEP0091: crypto.DEFAULT_ENCODING + Type: Runtime @@ -823,6 +1766,12 @@ The [`crypto.DEFAULT_ENCODING`][] property is deprecated. ### DEP0092: Top-level `this` bound to `module.exports` + Type: Documentation-only @@ -832,6 +1781,12 @@ or `module.exports` instead. ### DEP0093: crypto.fips is deprecated and replaced. + Type: Documentation-only @@ -840,6 +1795,12 @@ and `crypto.getFips()` instead. ### DEP0094: Using `assert.fail()` with more than one argument. + Type: Runtime @@ -849,6 +1810,12 @@ method. ### DEP0095: timers.enroll() + Type: Runtime @@ -857,6 +1824,12 @@ Type: Runtime ### DEP0096: timers.unenroll() + Type: Runtime @@ -865,6 +1838,12 @@ Type: Runtime ### DEP0097: MakeCallback with domain property + Type: Runtime @@ -874,6 +1853,15 @@ should start using the `async_context` variant of `MakeCallback` or ### DEP0098: AsyncHooks Embedder AsyncResource.emitBefore and AsyncResource.emitAfter APIs + Type: Runtime @@ -887,6 +1875,12 @@ https://github.com/nodejs/node/pull/18513 for more details. ### DEP0099: async context-unaware node::MakeCallback C++ APIs + Type: Compile-time @@ -896,6 +1890,14 @@ parameter. ### DEP0100: process.assert() + Type: Runtime @@ -905,6 +1907,12 @@ This was never a documented feature. ### DEP0101: --with-lttng + Type: End-of-Life @@ -912,6 +1920,12 @@ The `--with-lttng` compile-time option has been removed. ### DEP0102: Using `noAssert` in Buffer#(read|write) operations. + Type: End-of-Life @@ -921,6 +1935,15 @@ could lead to hard to find errors and crashes. ### DEP0103: process.binding('util').is[...] typechecks + Type: Documentation-only (supports [`--pending-deprecation`][]) @@ -932,6 +1955,12 @@ This deprecation has been superseded by the deprecation of the ### DEP0104: process.env string coercion + Type: Documentation-only (supports [`--pending-deprecation`][]) @@ -943,6 +1972,15 @@ assigning it to `process.env`. ### DEP0105: decipher.finaltol + Type: End-of-Life @@ -952,6 +1990,15 @@ Type: End-of-Life ### DEP0106: crypto.createCipher and crypto.createDecipher + Type: Runtime @@ -964,6 +2011,15 @@ initialization vectors. It is recommended to derive a key using ### DEP0107: tls.convertNPNProtocols() + Type: End-of-Life @@ -972,6 +2028,12 @@ core and obsoleted by the removal of NPN (Next Protocol Negotiation) support. ### DEP0108: zlib.bytesRead + Type: Documentation-only @@ -982,6 +2044,12 @@ expose values under these names. ### DEP0109: http, https, and tls support for invalid URLs + Type: Runtime @@ -994,6 +2062,12 @@ deprecated and support will be removed in the future. ### DEP0110: vm.Script cached data + Type: Documentation-only @@ -1002,6 +2076,12 @@ The `produceCachedData` option is deprecated. Use ### DEP0111: process.binding() + Type: Documentation-only @@ -1010,6 +2090,12 @@ only. Use of `process.binding()` by userland code is unsupported. ### DEP0112: dgram private APIs + Type: Runtime @@ -1022,6 +2108,12 @@ accessed outside of Node.js core: `Socket.prototype._handle`, ### DEP0113: Cipher.setAuthTag(), Decipher.getAuthTag() + Type: Runtime @@ -1032,6 +2124,12 @@ release. ### DEP0114: crypto._toBuf() + Type: Runtime @@ -1040,6 +2138,12 @@ of Node.js core and will be removed in the future. ### DEP0115: crypto.prng(), crypto.pseudoRandomBytes(), crypto.rng() + Type: Runtime @@ -1051,6 +2155,12 @@ future release. ### DEP0116: Legacy URL API + Type: Documentation From 4af8bf7665632bb42970196cb5e4c72016c13f07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Sun, 9 Sep 2018 02:18:08 +0200 Subject: [PATCH 3/5] fixup! tools: fix doc tool behavior for version arrays --- tools/doc/html.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tools/doc/html.js b/tools/doc/html.js index 7ae818b7a2567c..c0a94b6534b171 100644 --- a/tools/doc/html.js +++ b/tools/doc/html.js @@ -329,9 +329,9 @@ function parseYAML(text) { } function minVersion(a) { - if (!Array.isArray(a)) - return a; - return a.reduce((min, e) => !min || versionSort(min, e) < 0 ? e : min); + return common.arrify(a).reduce((min, e) => { + return !min || versionSort(min, e) < 0 ? e : min; + }); } const numberRe = /^\d*/; From 9fc6944c50c55b15b8f4070afd39cddf8f62daff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Sun, 9 Sep 2018 23:56:57 +0200 Subject: [PATCH 4/5] fixup! doc: add full deprecation history --- doc/api/deprecations.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 661db7394033f8..515d41f5e0625b 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -870,6 +870,7 @@ The [`tls.CryptoStream`][] class was removed. Please use ### DEP0043: tls.SecurePair Type: Documentation-only @@ -1280,6 +1289,12 @@ changes: - version: v8.0.0 pr-url: https://github.com/nodejs/node/pull/11349 description: Runtime deprecation. + - version: v6.12.0 + pr-url: https://github.com/nodejs/node/pull/10116 + description: A deprecation code has been assigned. + - version: v6.0.0 + pr-url: https://github.com/nodejs/node/pull/6063 + description: Documentation-only deprecation. - version: v0.11.15 pr-url: - https://github.com/nodejs/node-v0.x-archive/pull/8695