From cb7d8a0bf7839c3a639677cfae78b5ecc09e91b9 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 09:51:44 -0700 Subject: [PATCH 01/10] doc: edit text for DEP0104 Make the deprecation message a bit clear and concise. --- doc/api/deprecations.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 2101f462405a48..975a514fce9738 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -949,11 +949,11 @@ methods in particular can be replaced by using [`util.types`][]. Type: Documentation-only (supports [`--pending-deprecation`][]) -Currently when assigning a property to [`process.env`][], the assigned value is -implicitly converted to a string if it is not a string. This behavior is -deprecated if the assigned value is not a string, boolean, or number. In the -future, such assignment may result in a thrown error. Please convert the -property to a string before assigning it to `process.env`. +When assigning a non-string property to [`process.env`][], the assigned value is +implicitly converted to a string. This behavior is deprecated if the assigned +value is not a string, boolean, or number. In the future, such assignment may +result in a thrown error. Please convert the property to a string before +assigning it to `process.env`. ### DEP0105: decipher.finaltol From 10e564f3a426bf60c48a4199122fbe46ddc16ac4 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 09:53:42 -0700 Subject: [PATCH 02/10] doc: edit text for DEP0101 Make the text slightly more concise. Fix awkward verb tense. --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 975a514fce9738..cd10c8db6297db 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -925,7 +925,7 @@ This was never a documented feature. Type: End-of-Life -The `--with-lttng` compile time option is removed. +The `--with-lttng` compile-time option has been removed. ### DEP0102: Using `noAssert` in Buffer#(read|write) operations. From 277933a5e83d38de44f3ece47dc25191af9dcaf5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 09:55:05 -0700 Subject: [PATCH 03/10] doc: edit text for DEP0012 Fix awkward verb tense. --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index cd10c8db6297db..494e60fa68ab70 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -161,7 +161,7 @@ instead. Type: End-of-Life -`Domain.dispose()` is removed. Recover from failed I/O actions +`Domain.dispose()` has been removed. Recover from failed I/O actions explicitly via error event handlers set on the domain instead. From b836636a373ec31371aee5c686482dfd35d482fb Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 09:56:45 -0700 Subject: [PATCH 04/10] doc: edit text for DEP0094 Make deprecation text slightly more concise and direct. --- doc/api/deprecations.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 494e60fa68ab70..4b1be528cb09a7 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -860,9 +860,9 @@ and `crypto.getFips()` instead. Type: Runtime -Using `assert.fail()` with more than one argument has no benefit over writing an -individual error message. Either use `assert.fail()` with one argument or switch -to one of the other assert methods. +Using `assert.fail()` with more than one argument is deprecated. Use +`assert.fail()` with only one argument or use a different `assert` module +method. ### DEP0095: timers.enroll() From c7379705bee7daa5bbc0db986af004cfe685004a Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:00:19 -0700 Subject: [PATCH 05/10] doc: fix text for DEP0085 Fix a typographical error in deprecation text. Convert run-on sentence to two sentences (one in parentheses). --- doc/api/deprecations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 4b1be528cb09a7..bd91d59e7093bd 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -798,8 +798,8 @@ code modification is necessary if that is done. Type: End-of-Life -The AsyncHooks Sensitive API was never documented and had various of minor -issues, see https://github.com/nodejs/node/issues/15572. Use the `AsyncResource` +The AsyncHooks Sensitive API was never documented and had various minor issues. +(See https://github.com/nodejs/node/issues/15572.) Use the `AsyncResource` API instead. From 8847c2373609ee2a99a8115770dd1822c0e4427b Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:03:45 -0700 Subject: [PATCH 06/10] doc edit text for DEP0082 Make deprecation text more concise and direct. --- doc/api/deprecations.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index bd91d59e7093bd..01902cd391a080 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -748,9 +748,8 @@ file descriptors. Type: Runtime -`REPLServer.prototype.memory()` is a function only necessary for the -internal mechanics of the `REPLServer` itself, and is therefore not -necessary in user space. +`REPLServer.prototype.memory()` is only necessary for the internal mechanics of +the `REPLServer` itself. Do not use this function. ### DEP0083: Disabling ECDH by setting ecdhCurve to false From afc49d688d5cbf55039ffa42207655f2c1f70e6e Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:05:44 -0700 Subject: [PATCH 07/10] doc: fix minor typographical error in DEP0079 text Change `backwards compatibility` to `backward compatibility`. (It's confusing because "backwards compatible" is acceptable because "backwards" can be used as an adverb like that. However, as an adjective, as in "backward compatibility", only "backward" will do. Easiest solution: Always use "backward" because it is OK in both cases. This is all compounded by the US vs UK English thing. US English tends to favor "backward", and we standardize on US English, so that's another point in favor of "backward" over "backwards" in this context.) --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 01902cd391a080..5b1ea7d34cfc0a 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -722,7 +722,7 @@ Type: Runtime Using a property named `inspect` on an object to specify a custom inspection function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][] -instead. For backwards compatibility with Node.js prior to version 6.4.0, both +instead. For backward compatibility with Node.js prior to version 6.4.0, both may be specified. From cc8b1fc42de5f8658eb5e248dbc0abab205ede3d Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:11:02 -0700 Subject: [PATCH 08/10] doc: minor edit to DEP0065 Use "Node.js 6.0.0" instead of "Node.js v6.0.0". (We decided to drop "v" before version numbers to avoid confusion with the V8 JavaScript engine.) --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 5b1ea7d34cfc0a..473d1040ba9e24 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -569,7 +569,7 @@ Type: End-of-Life The `repl` module's `REPL_MODE_MAGIC` constant, used for `replMode` option, has been removed. Its behavior has been functionally identical to that of -`REPL_MODE_SLOPPY` since Node.js v6.0.0, when V8 5.0 was imported. Please use +`REPL_MODE_SLOPPY` since Node.js 6.0.0, when V8 5.0 was imported. Please use `REPL_MODE_SLOPPY` instead. The `NODE_REPL_MODE` environment variable is used to set the underlying From 9b3dceaf8c67c7528da2b6d4f6730413bc6050af Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:14:25 -0700 Subject: [PATCH 09/10] doc: edit text for DEP0013 * v10.0.0 -> Node.js 10.0.0 * Parenthetical with URL rather than "PR" as a lot of people may not know what "PR" stands for but they will know what a URL is. Plus not hiding the URL means the text is more copy/paste-able. In this particular case, "PR 12562" is not more useful or informative than https://github.com/nodejs/node/pull/12562 so just use the URL. --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 473d1040ba9e24..923f38a36bcb59 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -170,7 +170,7 @@ explicitly via error event handlers set on the domain instead. Type: End-of-Life Calling an asynchronous function without a callback throws a `TypeError` -v10.0.0 onwards. Refer: [PR 12562](https://github.com/nodejs/node/pull/12562). +in Node.js 10.0.0 onwards. (See https://github.com/nodejs/node/pull/12562.) ### DEP0014: fs.read legacy String interface From 4b73984bf0e7ac4ca033f609c85c1c0a90f604ce Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 4 May 2018 10:22:09 -0700 Subject: [PATCH 10/10] doc: edit text about revoking deprecations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * "un-deprecation" ಠ_ಠ -> "revoking deprecations" * "From time-to-time" -> "Occastionally" * "semver-major" and "semver-minor" are jargon that readers who don't follow our issue tracker will not know. Remove the sentence as it doesn't really impact end users. The deprecation is revoked when it is revoked. Rules around the releases where deprecations can be revoked may be added to the COLLABORATOR_GUIDE in the extensive section about deprecations there. If so, great, but let's still remove it here as having the information scattered in two places makes it likely that one will be edited to contradict the other and then it won't be clear which one is correct. * Remove unneeded italics. The italicized sentence is not hugely critical information that we desperately want users to know. Most users won't care. They will only care about the deprecation message that they are looking up at that moment. --- doc/api/deprecations.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 923f38a36bcb59..8ac5f098bb632d 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -30,12 +30,11 @@ cause an error to be thrown. An End-of-Life deprecation is used to identify code that either has been removed or will soon be removed from Node.js. -## Un-deprecation +## Revoking deprecations -From time-to-time the deprecation of an API may be reversed. Such action may -happen in either a semver-minor or semver-major release. In such situations, +Occasionally, the deprecation of an API may be reversed. In such situations, this document will be updated with information relevant to the decision. -*However, the deprecation identifier will not be modified*. +However, the deprecation identifier will not be modified. ## List of Deprecated APIs