From b3d637e8f1970d52f4de3485e536fcb575dedb2b Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Fri, 10 Aug 2018 21:37:53 -0700
Subject: [PATCH 1/2] doc: discuss special protocol handling

Fixes: https://github.com/nodejs/node/issues/13523
---
 doc/api/url.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/doc/api/url.md b/doc/api/url.md
index 64b7b444c54ffd..0b55998d8ac217 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -389,6 +389,46 @@ console.log(myURL.href);
 
 Invalid URL protocol values assigned to the `protocol` property are ignored.
 
+##### Special Schemes
+
+The WHATWG URL Standard considers a handful of URL protocol schemes to be
+"special" in terms of how those are parsed and serialized. When a URL is
+parsed using one of these special protocols, the `url.protocol` property
+may be changed to another special protocol but cannot be changed to a
+non-special protocol, and vice versa.
+
+For instance, changing from `http` to `https` works:
+
+```js
+const u = new URL('http://example.org');
+u.protocol = 'https';
+console.log(u.href);
+// https://example.org
+```
+
+However, changing from `http` to a hypothetical `fish` protocol does not
+because the new protocol is not considered "special".
+
+```js
+const u = new URL('http://example.org');
+u.protocol = 'fish';
+console.log(u.href);
+// http://example.org
+```
+
+Likewise, changing from a non-special protocol to a special protocol is also
+not permitted:
+
+```js
+const u = new URL('fish://example.org');
+u.protocol = 'http';
+console.log(u.href);
+// fish://example.org
+```
+
+The protocol schemes considered to be special by the WHATWG URL Standard
+include: `ftp`, `file`, `gopher`, `http`, `https`, `ws`, and `wss`.
+
 #### url.search
 
 * {string}

From 698547257d78110161a4353ea1042a55b5cc04ca Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 10 Aug 2018 22:18:09 -0700
Subject: [PATCH 2/2] squash! nits

---
 doc/api/url.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/api/url.md b/doc/api/url.md
index 0b55998d8ac217..7a101f6706f36f 100644
--- a/doc/api/url.md
+++ b/doc/api/url.md
@@ -391,8 +391,8 @@ Invalid URL protocol values assigned to the `protocol` property are ignored.
 
 ##### Special Schemes
 
-The WHATWG URL Standard considers a handful of URL protocol schemes to be
-"special" in terms of how those are parsed and serialized. When a URL is
+The [WHATWG URL Standard][] considers a handful of URL protocol schemes to be
+_special_ in terms of how they are parsed and serialized. When a URL is
 parsed using one of these special protocols, the `url.protocol` property
 may be changed to another special protocol but cannot be changed to a
 non-special protocol, and vice versa.
@@ -407,7 +407,7 @@ console.log(u.href);
 ```
 
 However, changing from `http` to a hypothetical `fish` protocol does not
-because the new protocol is not considered "special".
+because the new protocol is not special.
 
 ```js
 const u = new URL('http://example.org');