From 3a04026adc306bad0219906534165b9e13d0a962 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Wed, 5 Sep 2018 11:33:20 -0700
Subject: [PATCH 1/2] url: docs deprecate legacy url API

---
 doc/api/deprecations.md | 16 ++++++++++++++++
 doc/api/url.md          | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 10ffa49f4d5207..ea16a2ed94ec8d 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -1050,6 +1050,16 @@ deprecated along with the undocumented aliases `crypto.prng()` and
 `crypto.rng()` in favor of [`crypto.randomBytes()`][] and will be removed in a
 future release.
 
+<a id="DEP00XX"></a>
+### DEP00XX: Legacy URL API
+
+Type: Documentation
+
+The [Legacy URL API][] is deprecated in favor of the newer standardized
+[WHATWG URL][] implementation. This includes uses of [`url.format()`][],
+[`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][].
+
+
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
@@ -1108,6 +1118,9 @@ future release.
 [`tls.TLSSocket`]: tls.html#tls_class_tls_tlssocket
 [`tls.checkServerIdentity()`]: tls.html#tls_tls_checkserveridentity_hostname_cert
 [`tls.createSecureContext()`]: tls.html#tls_tls_createsecurecontext_options
+[`url.format()`]: url.html#url_url_format_urlobject
+[`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost
+[`url.resolve()`]: url.html#url_url_resolve_from_to
 [`util._extend()`]: util.html#util_util_extend_target_source
 [`util.debug()`]: util.html#util_util_debug_string
 [`util.error()`]: util.html#util_util_error_strings
@@ -1139,5 +1152,8 @@ future release.
 [alloc_unsafe_size]: buffer.html#buffer_class_method_buffer_allocunsafe_size
 [from_arraybuffer]: buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length
 [from_string_encoding]: buffer.html#buffer_class_method_buffer_from_string_encoding
+[Legacy URL API]: url.html#url_legacy_url_api
+[legacy `urlObject`]: url.html#url_legacy_urlobject
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
+[WHATWG URL]: url.html#url_the_whatwg_url_api
 [`REPLServer.clearBufferedCommand()`]: repl.html#repl_replserver_clearbufferedcommand
diff --git a/doc/api/url.md b/doc/api/url.md
index cd817bf304b19e..33b99398eeeb28 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -964,7 +964,15 @@ pathToFileURL('/some/path%.js');    // Correct:   file:///some/path%25 (POSIX)
 
 ## Legacy URL API
 
+> Stability: 0 - Deprecated: Use the WHATWG URL API instead.
+
 ### Legacy `urlObject`
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/22715
+    description: The Legacy URL API is deprecated. Use the WHATWG URL API.
+-->
 
 The legacy `urlObject` (`require('url').Url`) is created and returned by the
 `url.parse()` function.
@@ -1070,6 +1078,9 @@ forward-slash characters (`/`) are required following the colon in the
 <!-- YAML
 added: v0.1.25
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/22715
+    description: The Legacy URL API is deprecated. Use the WHATWG URL API.
   - version: v7.0.0
     pr-url: https://github.com/nodejs/node/pull/7234
     description: URLs with a `file:` scheme will now always use the correct
@@ -1158,6 +1169,9 @@ The formatting process operates as follows:
 <!-- YAML
 added: v0.1.25
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/22715
+    description: The Legacy URL API is deprecated. Use the WHATWG URL API.
   - version: v9.0.0
     pr-url: https://github.com/nodejs/node/pull/13606
     description: The `search` property on the returned URL object is now `null`
@@ -1186,6 +1200,9 @@ A `URIError` is thrown if the `auth` property is present but cannot be decoded.
 <!-- YAML
 added: v0.1.25
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/22715
+    description: The Legacy URL API is deprecated. Use the WHATWG URL API.
   - version: v6.6.0
     pr-url: https://github.com/nodejs/node/pull/8215
     description: The `auth` fields are now kept intact when `from` and `to`

From 86698e05605d4cfaf99b3d294102413f1c4f7295 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 7 Sep 2018 14:18:38 -0700
Subject: [PATCH 2/2] Update deprecations.md

---
 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 ea16a2ed94ec8d..c843fc7c20f4f6 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -1055,9 +1055,9 @@ future release.
 
 Type: Documentation
 
-The [Legacy URL API][] is deprecated in favor of the newer standardized
-[WHATWG URL][] implementation. This includes uses of [`url.format()`][],
-[`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][].
+The [Legacy URL API][] is deprecated. This includes [`url.format()`][],
+[`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][]. Please
+use the [WHATWG URL API][] instead.
 
 
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
@@ -1108,6 +1108,7 @@ The [Legacy URL API][] is deprecated in favor of the newer standardized
 [`os.tmpdir()`]: os.html#os_os_tmpdir
 [`process.env`]: process.html#process_process_env
 [`punycode`]: punycode.html
+[`REPLServer.clearBufferedCommand()`]: repl.html#repl_replserver_clearbufferedcommand
 [`require.extensions`]: modules.html#modules_require_extensions
 [`script.createCachedData()`]: vm.html#vm_script_createcacheddata
 [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args
@@ -1155,5 +1156,4 @@ The [Legacy URL API][] is deprecated in favor of the newer standardized
 [Legacy URL API]: url.html#url_legacy_url_api
 [legacy `urlObject`]: url.html#url_legacy_urlobject
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
-[WHATWG URL]: url.html#url_the_whatwg_url_api
-[`REPLServer.clearBufferedCommand()`]: repl.html#repl_replserver_clearbufferedcommand
+[WHATWG URL API]: url.html#url_the_whatwg_url_api