lib: add static identifier codes for all deprecations

Assigns a static identifier code to all runtime and documentation
only deprecations. The identifier code is included in the emitted
DeprecationWarning.

Also adds a deprecations.md to the API docs to provide a central
location where deprecation codes can be referenced and explained.

PR-URL: https://github.com/nodejs/node/pull/10116
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Michal Zasso <targos@protonmail.com>
Reviewed-By: Fedor Indutny <fedor.indutny@gmail.com>

21 files changed, 57 insertions, 44 deletions

diff --git a/lib/_http_outgoing.js b/lib/_http_outgoing.js
index 30011e0915..f9df781751 100644
--- a/lib/_http_outgoing.js
+++ b/lib/_http_outgoing.js
@@ -738,4 +738,4 @@ OutgoingMessage.prototype.flushHeaders = function flushHeaders() {
 
 OutgoingMessage.prototype.flush = internalUtil.deprecate(function() {
   this.flushHeaders();
-}, 'OutgoingMessage.flush is deprecated. Use flushHeaders instead.');
+}, 'OutgoingMessage.flush is deprecated. Use flushHeaders instead.', 'DEP0001');
diff --git a/lib/_linklist.js b/lib/_linklist.js
index 1b709d6fbd..1d2e9fa4d4 100644
--- a/lib/_linklist.js
+++ b/lib/_linklist.js
@@ -3,4 +3,4 @@
 module.exports = require('internal/linkedlist');
 process.emitWarning(
   '_linklist module is deprecated. Please use a userland alternative.',
-  'DeprecationWarning');
+  'DeprecationWarning', 'DEP0002');
diff --git a/lib/_stream_writable.js b/lib/_stream_writable.js
index af97fc2d81..eedeb56e12 100644
--- a/lib/_stream_writable.js
+++ b/lib/_stream_writable.js
@@ -125,7 +125,7 @@ Object.defineProperty(WritableState.prototype, 'buffer', {
   get: internalUtil.deprecate(function() {
     return this.getBuffer();
   }, '_writableState.buffer is deprecated. Use _writableState.getBuffer ' +
-     'instead.')
+     'instead.', 'DEP0003')
 });
 
 // Test _writableState for inheritance to account for Duplex streams,
diff --git a/lib/_tls_legacy.js b/lib/_tls_legacy.js
index e765b2507e..83ee3e0f8f 100644
--- a/lib/_tls_legacy.js
+++ b/lib/_tls_legacy.js
@@ -479,6 +479,7 @@ CryptoStream.prototype._done = function() {
 
 
 // readyState is deprecated. Don't use it.
+// Deprecation Code: DEP0004
 Object.defineProperty(CryptoStream.prototype, 'readyState', {
   get: function() {
     if (this.connecting) {
diff --git a/lib/buffer.js b/lib/buffer.js
index 456580a5c0..0a8724bda4 100644
--- a/lib/buffer.js
+++ b/lib/buffer.js
@@ -65,14 +65,14 @@ function alignPool() {
 }
 
 /**
- * The Buffer() construtor is "soft deprecated" ... that is, it is deprecated
- * in the documentation and should not be used moving forward. Rather,
- * developers should use one of the three new factory APIs: Buffer.from(),
- * Buffer.allocUnsafe() or Buffer.alloc() based on their specific needs. There
- * is no hard deprecation because of the extent to which the Buffer constructor
- * is used in the ecosystem currently -- a hard deprecation would introduce too
- * much breakage at this time. It's not likely that the Buffer constructors
- * would ever actually be removed.
+ * The Buffer() construtor is deprecated in documentation and should not be
+ * used moving forward. Rather, developers should use one of the three new
+ * factory APIs: Buffer.from(), Buffer.allocUnsafe() or Buffer.alloc() based on
+ * their specific needs. There is no runtime deprecation because of the extent
+ * to which the Buffer constructor is used in the ecosystem currently -- a
+ * runtime deprecation would introduce too much breakage at this time. It's not
+ * likely that the Buffer constructors would ever actually be removed.
+ * Deprecation Code: DEP0005
  **/
 function Buffer(arg, encodingOrOffset, length) {
   // Common case.
diff --git a/lib/child_process.js b/lib/child_process.js
index b00e3829b4..409dfff170 100644
--- a/lib/child_process.js
+++ b/lib/child_process.js
@@ -324,8 +324,7 @@ const _deprecatedCustomFds = internalUtil.deprecate(
       return fd === -1 ? 'pipe' : fd;
     });
   }, 'child_process: options.customFds option is deprecated. ' +
-     'Use options.stdio instead.'
-);
+     'Use options.stdio instead.', 'DEP0006');
 
 function _convertCustomFds(options) {
   if (options.customFds && !options.stdio) {
diff --git a/lib/constants.js b/lib/constants.js
index fec7e13d94..c1cbf2db3c 100644
--- a/lib/constants.js
+++ b/lib/constants.js
@@ -1,8 +1,9 @@
 'use strict';
 
-// This module is soft-deprecated. Users should be directed towards using
-// the specific constants exposed by the individual modules on which they
-// are most relevant.
+// This module is deprecated in documentation only. Users should be directed
+// towards using the specific constants exposed by the individual modules on
+// which they are most relevant.
+// Deprecation Code: DEP0008
 const constants = process.binding('constants');
 Object.assign(exports,
               constants.os.errno,
diff --git a/lib/crypto.js b/lib/crypto.js
index 9180ce70dc..2d4695dc97 100644
--- a/lib/crypto.js
+++ b/lib/crypto.js
@@ -539,7 +539,7 @@ ECDH.prototype.getPublicKey = function getPublicKey(encoding, format) {
 
 const pbkdf2DeprecationWarning =
     internalUtil.deprecate(() => {}, 'crypto.pbkdf2 without specifying' +
-      ' a digest is deprecated. Please specify a digest');
+      ' a digest is deprecated. Please specify a digest', 'DEP0009');
 
 
 exports.pbkdf2 = function(password,
@@ -663,7 +663,7 @@ Object.defineProperty(exports, 'createCredentials', {
   get: internalUtil.deprecate(function() {
     return require('tls').createSecureContext;
   }, 'crypto.createCredentials is deprecated. ' +
-     'Use tls.createSecureContext instead.')
+     'Use tls.createSecureContext instead.', 'DEP0010')
 });
 
 Object.defineProperty(exports, 'Credentials', {
@@ -672,5 +672,5 @@ Object.defineProperty(exports, 'Credentials', {
   get: internalUtil.deprecate(function() {
     return require('tls').SecureContext;
   }, 'crypto.Credentials is deprecated. ' +
-     'Use tls.SecureContext instead.')
+     'Use tls.SecureContext instead.', 'DEP0011')
 });
diff --git a/lib/domain.js b/lib/domain.js
index c86af75c86..f45a623e8a 100644
--- a/lib/domain.js
+++ b/lib/domain.js
@@ -315,4 +315,4 @@ Domain.prototype.dispose = util.deprecate(function() {
   // so that it can't be entered or activated.
   this._disposed = true;
 }, 'Domain.dispose is deprecated. Recover from failed I/O actions explicitly ' +
-    'via error event handlers set on the domain instead.');
+    'via error event handlers set on the domain instead.', 'DEP0012');
diff --git a/lib/fs.js b/lib/fs.js
index 573ffec059..27e1a2e79c 100644
--- a/lib/fs.js
+++ b/lib/fs.js
@@ -68,8 +68,7 @@ function rethrow() {
   // TODO(thefourtheye) Throw error instead of warning in major version > 7
   process.emitWarning(
     'Calling an asynchronous function without callback is deprecated.',
-    'DeprecationWarning',
-    rethrow
+    'DeprecationWarning', 'DEP0013', rethrow
   );
 
   // Only enable in debug mode. A backtrace uses ~1000 bytes of heap space and
@@ -1943,6 +1942,7 @@ WriteStream.prototype.destroySoon = WriteStream.prototype.end;
 // todo(jasnell): "Docs-only" deprecation for now. This was never documented
 // so there's no documentation to modify. In the future, add a runtime
 // deprecation.
+// Deprecation ID: DEP0061
 Object.defineProperty(fs, 'SyncWriteStream', {
   configurable: true,
   writable: true,
diff --git a/lib/internal/bootstrap_node.js b/lib/internal/bootstrap_node.js
index 71a6c52904..efdbc5d9e3 100644
--- a/lib/internal/bootstrap_node.js
+++ b/lib/internal/bootstrap_node.js
@@ -204,7 +204,7 @@
       // getter
       const get = util.deprecate(function() {
         return this;
-      }, `'${name}' is deprecated, use 'global'`);
+      }, `'${name}' is deprecated, use 'global'`, 'DEP0016');
       // setter
       const set = util.deprecate(function(value) {
         Object.defineProperty(this, name, {
@@ -213,7 +213,7 @@
           enumerable: true,
           value: value
         });
-      }, `'${name}' is deprecated, use 'global'`);
+      }, `'${name}' is deprecated, use 'global'`, 'DEP0016');
       // define property
       Object.defineProperty(global, name, { get, set, configurable: true });
     });
diff --git a/lib/internal/cluster/worker.js b/lib/internal/cluster/worker.js
index fd46ed5710..687e4c12fe 100644
--- a/lib/internal/cluster/worker.js
+++ b/lib/internal/cluster/worker.js
@@ -23,10 +23,10 @@ function Worker(options) {
   defineProperty(this, 'suicide', {
     get: internalUtil.deprecate(
       () => this.exitedAfterDisconnect,
-      suicideDeprecationMessage),
+      suicideDeprecationMessage, 'DEP0007'),
     set: internalUtil.deprecate(
       (val) => { this.exitedAfterDisconnect = val; },
-      suicideDeprecationMessage),
+      suicideDeprecationMessage, 'DEP0007'),
     enumerable: true
   });
 
diff --git a/lib/internal/process.js b/lib/internal/process.js
index 44f1370459..3f050b42ca 100644
--- a/lib/internal/process.js
+++ b/lib/internal/process.js
@@ -130,7 +130,8 @@ function setupConfig(_source) {
                         'See https://github.com/nodejs/node/wiki/Intl');
       }
       return Reflect.construct(oldV8BreakIterator, arguments);
-    }, 'Intl.v8BreakIterator is deprecated and will be removed soon.');
+    }, 'Intl.v8BreakIterator is deprecated and will be removed soon.',
+                                                   'DEP0017');
     Object.defineProperty(Intl, 'v8BreakIterator', des);
   }
   // Don’t let icu_data_dir leak through.
diff --git a/lib/internal/process/promises.js b/lib/internal/process/promises.js
index 83dee491a5..0e382d11d5 100644
--- a/lib/internal/process/promises.js
+++ b/lib/internal/process/promises.js
@@ -70,7 +70,7 @@ function setupPromises(scheduleMicrotasks) {
         'Unhandled promise rejections are deprecated. In the future, ' +
         'promise rejections that are not handled will terminate the ' +
         'Node.js process with a non-zero exit code.',
-        'DeprecationWarning');
+        'DeprecationWarning', 'DEP0018');
     }
   }
   var deprecationWarned = false;
diff --git a/lib/internal/util.js b/lib/internal/util.js
index 42a0922d30..10844b6454 100644
--- a/lib/internal/util.js
+++ b/lib/internal/util.js
@@ -15,8 +15,8 @@ exports.customInspectSymbol = Symbol('util.inspect.custom');
 
 // All the internal deprecations have to use this function only, as this will
 // prepend the prefix to the actual message.
-exports.deprecate = function(fn, msg) {
-  return exports._deprecate(fn, msg);
+exports.deprecate = function(fn, msg, code) {
+  return exports._deprecate(fn, msg, code);
 };
 
 exports.error = function(msg) {
@@ -39,7 +39,7 @@ exports.trace = function(msg) {
 // Mark that a method should not be used.
 // Returns a modified function which warns once by default.
 // If --no-deprecation is set, then it is a no-op.
-exports._deprecate = function(fn, msg) {
+exports._deprecate = function(fn, msg, code) {
   // Allow for deprecating things in the process of starting up.
   if (global.process === undefined) {
     return function() {
@@ -51,11 +51,18 @@ exports._deprecate = function(fn, msg) {
     return fn;
   }
 
+  if (code !== undefined && typeof code !== 'string')
+    throw new TypeError('`code` argument must be a string');
+
   var warned = false;
   function deprecated() {
     if (!warned) {
       warned = true;
-      process.emitWarning(msg, 'DeprecationWarning', deprecated);
+      if (code !== undefined) {
+        process.emitWarning(msg, 'DeprecationWarning', code, deprecated);
+      } else {
+        process.emitWarning(msg, 'DeprecationWarning', deprecated);
+      }
     }
     if (new.target) {
       return Reflect.construct(fn, arguments, new.target);
diff --git a/lib/module.js b/lib/module.js
index 09c4b85b9e..9a6b641a75 100644
--- a/lib/module.js
+++ b/lib/module.js
@@ -213,7 +213,7 @@ Module._findPath = function(request, paths, isMain) {
             'warning: require(\'.\') resolved outside the package ' +
             'directory. This functionality is deprecated and will be removed ' +
             'soon.',
-            'DeprecationWarning');
+            'DeprecationWarning', 'DEP0019');
         }
       }
 
diff --git a/lib/net.js b/lib/net.js
index e4f97ab80d..1213098953 100644
--- a/lib/net.js
+++ b/lib/net.js
@@ -1131,9 +1131,10 @@ function Server(options, connectionListener) {
       }
       return this._connections;
     }, 'Server.connections property is deprecated. ' +
-       'Use Server.getConnections method instead.'),
+       'Use Server.getConnections method instead.', 'DEP0020'),
     set: internalUtil.deprecate((val) => (this._connections = val),
-                                'Server.connections property is deprecated.'),
+                                'Server.connections property is deprecated.',
+                                'DEP0020'),
     configurable: true, enumerable: false
   });
 
@@ -1546,7 +1547,8 @@ function emitCloseNT(self) {
 
 Server.prototype.listenFD = internalUtil.deprecate(function(fd, type) {
   return this.listen({ fd: fd });
-}, 'Server.listenFD is deprecated. Use Server.listen({fd: <number>}) instead.');
+}, 'Server.listenFD is deprecated. Use Server.listen({fd: <number>}) instead.',
+                                                   'DEP0021');
 
 Server.prototype._setupSlave = function(socketList) {
   this._usingSlaves = true;
diff --git a/lib/os.js b/lib/os.js
index a59cc49bae..7ab0ec5fa4 100644
--- a/lib/os.js
+++ b/lib/os.js
@@ -53,12 +53,14 @@ exports.tmpdir = function() {
 
 const tmpDirDeprecationMsg =
   'os.tmpDir() is deprecated. Use os.tmpdir() instead.';
-exports.tmpDir = internalUtil.deprecate(exports.tmpdir, tmpDirDeprecationMsg);
+exports.tmpDir = internalUtil.deprecate(exports.tmpdir,
+                                        tmpDirDeprecationMsg,
+                                        'DEP0022');
 
 exports.getNetworkInterfaces = internalUtil.deprecate(function() {
   return exports.networkInterfaces();
 }, 'os.getNetworkInterfaces is deprecated. ' +
-   'Use os.networkInterfaces instead.');
+   'Use os.networkInterfaces instead.', 'DEP0023');
 
 exports.EOL = isWindows ? '\r\n' : '\n';
 
diff --git a/lib/repl.js b/lib/repl.js
index 29f25a5c37..fed89146dc 100644
--- a/lib/repl.js
+++ b/lib/repl.js
@@ -1356,7 +1356,7 @@ REPLServer.prototype.convertToContext = util.deprecate(function(cmd) {
   }
 
   return cmd;
-}, 'replServer.convertToContext() is deprecated');
+}, 'replServer.convertToContext() is deprecated', 'DEP0024');
 
 function bailOnIllegalToken(parser) {
   return parser._literal === null &&
diff --git a/lib/sys.js b/lib/sys.js
index c94b032c64..4d7d305daa 100644
--- a/lib/sys.js
+++ b/lib/sys.js
@@ -6,4 +6,4 @@
 
 module.exports = require('util');
 process.emitWarning('sys is deprecated. Use util instead.',
-                    'DeprecationWarning');
+                    'DeprecationWarning', 'DEP0025');
diff --git a/lib/util.js b/lib/util.js
index 9d5909cdc7..46cde4d85b 100644
--- a/lib/util.js
+++ b/lib/util.js
@@ -993,26 +993,26 @@ exports.print = internalUtil.deprecate(function() {
   for (var i = 0, len = arguments.length; i < len; ++i) {
     process.stdout.write(String(arguments[i]));
   }
-}, 'util.print is deprecated. Use console.log instead.');
+}, 'util.print is deprecated. Use console.log instead.', 'DEP0026');
 
 
 exports.puts = internalUtil.deprecate(function() {
   for (var i = 0, len = arguments.length; i < len; ++i) {
     process.stdout.write(arguments[i] + '\n');
   }
-}, 'util.puts is deprecated. Use console.log instead.');
+}, 'util.puts is deprecated. Use console.log instead.', 'DEP0027');
 
 
 exports.debug = internalUtil.deprecate(function(x) {
   process.stderr.write(`DEBUG: ${x}\n`);
-}, 'util.debug is deprecated. Use console.error instead.');
+}, 'util.debug is deprecated. Use console.error instead.', 'DEP0028');
 
 
 exports.error = internalUtil.deprecate(function(x) {
   for (var i = 0, len = arguments.length; i < len; ++i) {
     process.stderr.write(arguments[i] + '\n');
   }
-}, 'util.error is deprecated. Use console.error instead.');
+}, 'util.error is deprecated. Use console.error instead.', 'DEP0029');
 
 
 exports._errnoException = function(err, syscall, original) {