From 7eaf98c74180842867a7059186ea6aa2e658ce8c Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Sat, 5 Nov 2016 17:05:20 -0700
Subject: [PATCH 1/2] lib: add --deprecate-soon and util.deprecateSoon()

This adds a non-intrusive mechanism for indicating that an API is
expected to be deprecated "soon" where "soon" means at least the
next semver-major Node.js release. The `DeprecateSoonWarning` is
only emitted if the `--deprecate-soon` command line option is
used which means the option will have zero impact for most
situations. For those developers who wish to be proactively
alerted to pending deprecations, use of the `--deprecate-soon`
option can be used in testing/CI environments to determine
which APIs may end up deprecated in the future.

It should be noted that a "deprecate soon" warning is just a
heads up, and that a decision can be made later NOT to
deprecate the API if the change is deemed to be too
intrusive.
---
 doc/api/cli.md                       |  7 ++++++
 doc/node.1                           |  4 +++
 lib/internal/util.js                 | 30 ++++++++++++++++++++++
 src/node.cc                          | 10 ++++++++
 src/node_config.cc                   |  3 +++
 src/node_internals.h                 |  2 ++
 test/parallel/test-deprecate-soon.js | 37 ++++++++++++++++++++++++++++
 7 files changed, 93 insertions(+)
 create mode 100644 test/parallel/test-deprecate-soon.js

diff --git a/doc/api/cli.md b/doc/api/cli.md
index b45dc8c63f86b3..802302486d6b93 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -107,6 +107,13 @@ added: v0.11.14
 
 Throw errors for deprecations.
 
+### `--deprecate-soon`
+<!-- YAML
+added: REPLACEME
+-->
+
+Show warnings for APIs that are expected to be deprecated soon.
+
 ### `--no-warnings`
 <!-- YAML
 added: v6.0.0
diff --git a/doc/node.1 b/doc/node.1
index ec41a44c7598c3..568e18cdb1daa8 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -103,6 +103,10 @@ Print stack traces for deprecations.
 .BR \-\-throw\-deprecation
 Throw errors for deprecations.
 
+.TP
+.BR \-\-deprecate-soon
+Show warnings for APIs that are expected to be deprecated soon.
+
 .TP
 .BR \-\-no\-warnings
 Silence all process warnings (including deprecations).
diff --git a/lib/internal/util.js b/lib/internal/util.js
index 4ada8dd0cc16f0..8d17093a89fe5f 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -161,3 +161,33 @@ exports.cachedResult = function cachedResult(fn) {
     return result;
   };
 };
+
+// Mark that a method is expected to be deprecated soon. Such
+// warnings are intended to be warnings to the ecosystem that
+// a deprecation is expected in the next major release.
+exports.deprecateSoon = function(fn, msg) {
+  if (process.binding('config').deprecateSoon !== true)
+    return fn;
+
+  var warned = false;
+  function deprecateSoon() {
+    if (!warned) {
+      warned = true;
+      process.emitWarning(msg, 'DeprecateSoonWarning', deprecateSoon);
+    }
+    if (new.target) {
+      return Reflect.construct(fn, arguments, new.target);
+    }
+    return fn.apply(this, arguments);
+  }
+  // The wrapper will keep the same prototype as fn to maintain prototype chain
+  Object.setPrototypeOf(deprecateSoon, fn);
+  if (fn.prototype) {
+    // Setting this (rather than using Object.setPrototype, as above) ensures
+    // that calling the unwrapped constructor gives an instanceof the wrapped
+    // constructor.
+    deprecateSoon.prototype = fn.prototype;
+  }
+
+  return deprecateSoon;
+};
diff --git a/src/node.cc b/src/node.cc
index ce49a5c431fd74..66fce63b8bec8a 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -188,6 +188,12 @@ bool trace_warnings = false;
 // that is used by lib/module.js
 bool config_preserve_symlinks = false;
 
+// Set in node.cc by ParseArgs when --deprecate-soon is used.
+// Used in node_config.cc to set a constant on process.binding('config')
+// that is used by the emitDeprecateSoonWarning() method in
+// lib/internal/util.js
+bool config_deprecate_soon = false;
+
 bool v8_initialized = false;
 
 // process-relative uptime base, initialized at start-up
@@ -3539,6 +3545,8 @@ static void PrintHelp() {
          "  --trace-deprecation   show stack traces on deprecations\n"
          "  --throw-deprecation   throw an exception anytime a deprecated "
          "function is used\n"
+         "  --deprecate--soon     show warnings for APIs that are expected\n"
+         "                        to be deprecated soon\n"
          "  --no-warnings         silence all process warnings\n"
          "  --trace-warnings      show stack traces on process warnings\n"
          "  --trace-sync-io       show stack trace when use of sync IO\n"
@@ -3695,6 +3703,8 @@ static void ParseArgs(int* argc,
       track_heap_objects = true;
     } else if (strcmp(arg, "--throw-deprecation") == 0) {
       throw_deprecation = true;
+    } else if (strcmp(arg, "--deprecate-soon") == 0) {
+      config_deprecate_soon = true;
     } else if (strncmp(arg, "--security-revert=", 18) == 0) {
       const char* cve = arg + 18;
       Revert(cve);
diff --git a/src/node_config.cc b/src/node_config.cc
index 401345f6a608be..f359df14fa91c1 100644
--- a/src/node_config.cc
+++ b/src/node_config.cc
@@ -44,6 +44,9 @@ void InitConfig(Local<Object> target,
 
   if (config_preserve_symlinks)
     READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
+
+  if (config_deprecate_soon)
+    READONLY_BOOLEAN_PROPERTY("deprecateSoon");
 }  // InitConfig
 
 }  // namespace node
diff --git a/src/node_internals.h b/src/node_internals.h
index ae284660782cfe..e2ca7fff3cbf52 100644
--- a/src/node_internals.h
+++ b/src/node_internals.h
@@ -41,6 +41,8 @@ extern const char* openssl_config;
 // that is used by lib/module.js
 extern bool config_preserve_symlinks;
 
+extern bool config_deprecate_soon;
+
 // Tells whether it is safe to call v8::Isolate::GetCurrent().
 extern bool v8_initialized;
 
diff --git a/test/parallel/test-deprecate-soon.js b/test/parallel/test-deprecate-soon.js
new file mode 100644
index 00000000000000..4f29e3a1ece50a
--- /dev/null
+++ b/test/parallel/test-deprecate-soon.js
@@ -0,0 +1,37 @@
+'use strict';
+
+// Tests the --deprecate-soon command line option and warning emission.
+
+const common = require('../common');
+const assert = require('assert');
+const spawnSync = require('child_process').spawnSync;
+const deprecateSoon = process.binding('config').deprecateSoon;
+
+if (process.argv[2] === 'child') {
+  const util = require('internal/util');
+  const fn = util.deprecateSoon(() => {}, 'this will be deprecated soon');
+
+  const count = deprecateSoon ? 1 : 0;
+  process.on('warning', common.mustCall((warning) => {
+    assert.strictEqual(warning.name, 'DeprecateSoonWarning');
+    assert.strictEqual(warning.message, 'this will be deprecated soon');
+  }, count));
+  fn();
+} else {
+  const options = [
+    '--expose-internals',
+    __filename,
+    'child'
+  ];
+
+  // Do not emit the deprecate soon warning
+  assert.strictEqual(
+    spawnSync(process.execPath, options).status, 0,
+    'deprecation warning was printed');
+
+  options.unshift('--deprecate-soon');
+
+  assert.strictEqual(
+    spawnSync(process.execPath, options).status, 0,
+    'deprecation warning was not printed properly');
+}

From 64f0f6790635a60c857d7a607c35418a466baa0d Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 7 Nov 2016 07:24:44 -0800
Subject: [PATCH 2/2] Switch to --deprecated-in-docs

---
 doc/api/cli.md                       |  4 ++--
 doc/node.1                           |  4 ++--
 lib/internal/util.js                 | 20 ++++++++++----------
 src/node.cc                          | 14 +++++++-------
 src/node_config.cc                   |  4 ++--
 src/node_internals.h                 |  2 +-
 test/parallel/test-deprecate-soon.js | 18 +++++++++---------
 7 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 802302486d6b93..03123a54f1b088 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -107,12 +107,12 @@ added: v0.11.14
 
 Throw errors for deprecations.
 
-### `--deprecate-soon`
+### `--deprecated-in-docs`
 <!-- YAML
 added: REPLACEME
 -->
 
-Show warnings for APIs that are expected to be deprecated soon.
+Show warnings for APIs that have been deprecated in the documentation.
 
 ### `--no-warnings`
 <!-- YAML
diff --git a/doc/node.1 b/doc/node.1
index 568e18cdb1daa8..f2b32bdd8c09ab 100644
--- a/doc/node.1
+++ b/doc/node.1
@@ -104,8 +104,8 @@ Print stack traces for deprecations.
 Throw errors for deprecations.
 
 .TP
-.BR \-\-deprecate-soon
-Show warnings for APIs that are expected to be deprecated soon.
+.BR \-\-deprecated-in-docs
+Show warnings for APIs that have been deprecated in the documentation.
 
 .TP
 .BR \-\-no\-warnings
diff --git a/lib/internal/util.js b/lib/internal/util.js
index 8d17093a89fe5f..00262deb770fba 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -162,18 +162,18 @@ exports.cachedResult = function cachedResult(fn) {
   };
 };
 
-// Mark that a method is expected to be deprecated soon. Such
-// warnings are intended to be warnings to the ecosystem that
-// a deprecation is expected in the next major release.
-exports.deprecateSoon = function(fn, msg) {
-  if (process.binding('config').deprecateSoon !== true)
+// Used to emit a warning when a function has been deprecated
+// in the docs. Only has an effect when the --deprecated-in-docs
+// command line argument is used (off by default).
+exports.deprecatedInDocs = function(fn, msg) {
+  if (process.binding('config').deprecateInDocs !== true)
     return fn;
 
   var warned = false;
-  function deprecateSoon() {
+  function deprecatedInDocs() {
     if (!warned) {
       warned = true;
-      process.emitWarning(msg, 'DeprecateSoonWarning', deprecateSoon);
+      process.emitWarning(msg, 'DeprecatedInDocsWarning', deprecatedInDocs);
     }
     if (new.target) {
       return Reflect.construct(fn, arguments, new.target);
@@ -181,13 +181,13 @@ exports.deprecateSoon = function(fn, msg) {
     return fn.apply(this, arguments);
   }
   // The wrapper will keep the same prototype as fn to maintain prototype chain
-  Object.setPrototypeOf(deprecateSoon, fn);
+  Object.setPrototypeOf(deprecatedInDocs, fn);
   if (fn.prototype) {
     // Setting this (rather than using Object.setPrototype, as above) ensures
     // that calling the unwrapped constructor gives an instanceof the wrapped
     // constructor.
-    deprecateSoon.prototype = fn.prototype;
+    deprecatedInDocs.prototype = fn.prototype;
   }
 
-  return deprecateSoon;
+  return deprecatedInDocs;
 };
diff --git a/src/node.cc b/src/node.cc
index 66fce63b8bec8a..4926d2b6594a78 100644
--- a/src/node.cc
+++ b/src/node.cc
@@ -188,11 +188,11 @@ bool trace_warnings = false;
 // that is used by lib/module.js
 bool config_preserve_symlinks = false;
 
-// Set in node.cc by ParseArgs when --deprecate-soon is used.
+// Set in node.cc by ParseArgs when --deprecated-in-docs is used.
 // Used in node_config.cc to set a constant on process.binding('config')
-// that is used by the emitDeprecateSoonWarning() method in
+// that is used by the emitDeprecatedInDocsWarning() method in
 // lib/internal/util.js
-bool config_deprecate_soon = false;
+bool config_deprecated_in_docs = false;
 
 bool v8_initialized = false;
 
@@ -3545,8 +3545,8 @@ static void PrintHelp() {
          "  --trace-deprecation   show stack traces on deprecations\n"
          "  --throw-deprecation   throw an exception anytime a deprecated "
          "function is used\n"
-         "  --deprecate--soon     show warnings for APIs that are expected\n"
-         "                        to be deprecated soon\n"
+         "  --deprecated-in-docs  show warnings for APIs that are deprecated\n"
+         "                        in the docs\n"
          "  --no-warnings         silence all process warnings\n"
          "  --trace-warnings      show stack traces on process warnings\n"
          "  --trace-sync-io       show stack trace when use of sync IO\n"
@@ -3703,8 +3703,8 @@ static void ParseArgs(int* argc,
       track_heap_objects = true;
     } else if (strcmp(arg, "--throw-deprecation") == 0) {
       throw_deprecation = true;
-    } else if (strcmp(arg, "--deprecate-soon") == 0) {
-      config_deprecate_soon = true;
+    } else if (strcmp(arg, "--deprecated-in-docs") == 0) {
+      config_deprecated_in_docs = true;
     } else if (strncmp(arg, "--security-revert=", 18) == 0) {
       const char* cve = arg + 18;
       Revert(cve);
diff --git a/src/node_config.cc b/src/node_config.cc
index f359df14fa91c1..d148ce145adfdd 100644
--- a/src/node_config.cc
+++ b/src/node_config.cc
@@ -45,8 +45,8 @@ void InitConfig(Local<Object> target,
   if (config_preserve_symlinks)
     READONLY_BOOLEAN_PROPERTY("preserveSymlinks");
 
-  if (config_deprecate_soon)
-    READONLY_BOOLEAN_PROPERTY("deprecateSoon");
+  if (config_deprecated_in_docs)
+    READONLY_BOOLEAN_PROPERTY("deprecatedInDocs");
 }  // InitConfig
 
 }  // namespace node
diff --git a/src/node_internals.h b/src/node_internals.h
index e2ca7fff3cbf52..d356701b7566ec 100644
--- a/src/node_internals.h
+++ b/src/node_internals.h
@@ -41,7 +41,7 @@ extern const char* openssl_config;
 // that is used by lib/module.js
 extern bool config_preserve_symlinks;
 
-extern bool config_deprecate_soon;
+extern bool config_deprecated_in_docs;
 
 // Tells whether it is safe to call v8::Isolate::GetCurrent().
 extern bool v8_initialized;
diff --git a/test/parallel/test-deprecate-soon.js b/test/parallel/test-deprecate-soon.js
index 4f29e3a1ece50a..68635244482274 100644
--- a/test/parallel/test-deprecate-soon.js
+++ b/test/parallel/test-deprecate-soon.js
@@ -1,21 +1,20 @@
 'use strict';
 
-// Tests the --deprecate-soon command line option and warning emission.
+// Tests the --deprecated-in-docs command line option and warning emission.
 
 const common = require('../common');
 const assert = require('assert');
 const spawnSync = require('child_process').spawnSync;
-const deprecateSoon = process.binding('config').deprecateSoon;
+const deprecateInDocs = process.binding('config').deprecateInDocs;
 
 if (process.argv[2] === 'child') {
   const util = require('internal/util');
-  const fn = util.deprecateSoon(() => {}, 'this will be deprecated soon');
+  const fn = util.deprecatedInDocs(() => {}, 'this is deprecated in the docs');
 
-  const count = deprecateSoon ? 1 : 0;
   process.on('warning', common.mustCall((warning) => {
-    assert.strictEqual(warning.name, 'DeprecateSoonWarning');
-    assert.strictEqual(warning.message, 'this will be deprecated soon');
-  }, count));
+    assert.strictEqual(warning.name, 'DeprecatedInDocsWarning');
+    assert.strictEqual(warning.message, 'this is deprecated in the docs');
+  }, deprecateInDocs ? 1 : 0));
   fn();
 } else {
   const options = [
@@ -24,13 +23,14 @@ if (process.argv[2] === 'child') {
     'child'
   ];
 
-  // Do not emit the deprecate soon warning
+  // Do not emit the deprecated in docs warning
   assert.strictEqual(
     spawnSync(process.execPath, options).status, 0,
     'deprecation warning was printed');
 
-  options.unshift('--deprecate-soon');
+  options.unshift('--deprecated-in-docs');
 
+  // Emit the deprecated in docs warning
   assert.strictEqual(
     spawnSync(process.execPath, options).status, 0,
     'deprecation warning was not printed properly');