doc: graduate WHATWG URL from Experimental #12710

jasnell · 2017-04-28T00:16:21Z

Thanks to amazing effort from @TimothyGu, @joyeecheung, @watilde and @targos the WHATWG URL Parser should be ready to graduate from Experimental status as a new fully support API.
🎉🎈🍰🚀

/cc @nodejs/ctc

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc (url)

hiroppy · 2017-04-28T00:32:03Z

🎉

Trott · 2017-04-28T01:54:05Z

doc/api/url.md

-The `url` module provides an *experimental* implementation of the
-[WHATWG URL Standard][] as an alternative to the existing `url.parse()` API.
+The `url` module provides an implementation of the [WHATWG URL Standard][] as
+an alternative to the existing `url.parse()` API.


Nit: Maybe remove existing.

TimothyGu

LGTM, though I'd wait for #12683 to be applied first and then incorporate my version of this PR, which updates the changes YAML property for affected APIs as well.

jasnell · 2017-04-28T12:48:51Z

@TimothyGu ... +1 .. If you'd like, feel free to merge TimothyGu@213b9ce into this PR. I plan to get #12683 landed today.

sam-github · 2017-04-28T17:32:21Z

LGTM

Not sure if its relevant to this specific PR, but for a non-experimental feature, the docs are still incomplete:

They (EDIT: "should") lead with a discussion of why Node.js has two url APIs, how they interact (url.format supports both), and how they differ. Some advice on which to use would be useful.
The docs should have YAML markup describing when the APIs were added, particularly since they don't (yet) exist in 6.x, and may never in 4.x.
Personally, I think there should be a parallel section to The WHATWG URL API, maybe The legacy URL API (traditional? backwards compatible? other?), so its clear there are two, and which one a reader is looking at.

jasnell · 2017-04-28T21:03:50Z

Added a new commit that restructures the url.md documentation page a bit more. PTAL (especially those who had already signed off)

Fishrock123 · 2017-04-28T23:12:25Z

Should this be ctc-review?

jasnell · 2017-04-28T23:35:08Z

Probably :)

TimothyGu · 2017-04-29T19:19:07Z

I've taken the liberty to incorporate the changes I had in my local branch, which updates the YAML annotations for added and stable version information (/cc @sam-github). I've also shuffled the content around a bit, not too significantly though.

For those who cannot render the updated documentation page, the page layout now looks something like this:

Updated table of contents

URL
- The WHATWG URL API
  - Class: URL
    - Constructor: new URL(input[, base])
    - url.hash
    - url.host
    - url.hostname
    - etc.
  - Class: URLSearchParams
    - Constructor: new URLSearchParams()
    - Constructor: new URLSearchParams(string)
    - Constructor: new URLSearchParams(obj)
    - Constructor: new URLSearchParams(iterable)
    - urlSearchParams.append(name, value)
    - urlSearchParams.delete(name)
    - etc.
  - url.domainToASCII(domain)
  - url.domainToUnicode(domain)
  - url.format(URL[, options])
- Legacy URL API
  - Legacy urlObject
    - urlObject.auth
    - urlObject.hash
    - urlObject.host
    - etc.
  - url.format(urlObject)
  - url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
  - url.resolve(from, to)
- Percent-Encoding in URLs
  - Legacy API
  - WHATWG API

joyeecheung

LGTM with a question.

Aside: I think somewhere in the documentation we should mention that new URL(input) without a base doesn't work on relative urls (e.g. req.url), but that can be done in another PR

joyeecheung · 2017-04-30T14:44:21Z

doc/api/url.md

+For example, the ASCII space character (`' '`) is encoded as `%20`. The ASCII
+forward slash (`/`) character is encoded as `%3C`.
+
+<a id="whatwg-percent-encoding"></a>


Why is this anchor moved?

It is moved since James refactored the original chapter "Percent-Encoding in WHATWG" to a chapter "Percent-Encoding" with two sections "Legacy" and "WHATWG". The anchor goes with the description of WHATWG URL.

ChALkeR · 2017-05-04T14:32:00Z

Note: this or #12723 fixes #11362, whichever lands first.

jasnell · 2017-05-28T15:14:01Z

@nodejs/ctc ... any objections on this landing for 8.0.0? If not, I will land this on Monday and pull it in to 8.0.0

gibfahn · 2017-05-28T16:19:17Z

Should this be ctc-review?

Probably :)

@nodejs/ctc PTAL

targos · 2017-05-29T13:54:35Z

+1 for landing on 8.0.0

jasnell · 2017-05-29T14:34:34Z

Given that there have been no objections raised, and we have sign off that includes two CTC members, I'm landing this.

PR-URL: #12710 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Sam Roberts <[email protected]>

jasnell · 2017-05-29T14:42:13Z

Landed in 10754b6 and dbbe1f1! 🎉 🎈 🍰

All, keep in mind that this means all PRs that touch the URL are now subject to the semver rules

PR-URL: #12710 Reviewed-By: Joyee Cheung <[email protected]> Reviewed-By: Daijiro Wachi <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Gibson Fahnestock <[email protected]> Reviewed-By: Sam Roberts <[email protected]>

* **Async Hooks** * The `async_hooks` module has landed in core [[`4a7233c178`](nodejs@4a7233c178)] [nodejs#12892](nodejs#12892). * **Buffer** * Using the `--pending-deprecation` flag will cause Node.js to emit a deprecation warning when using `new Buffer(num)` or `Buffer(num)`. [[`d2d32ea5a2`](nodejs@d2d32ea5a2)] [nodejs#11968](nodejs#11968). * `new Buffer(num)` and `Buffer(num)` will zero-fill new `Buffer` instances [[`7eb1b4658e`](nodejs@7eb1b4658e)] [nodejs#12141](nodejs#12141). * Many `Buffer` methods now accept `Uint8Array` as input [[`beca3244e2`](nodejs@beca3244e2)] [nodejs#10236](nodejs#10236). * **Child Process** * Argument and kill signal validations have been improved [[`97a77288ce`](nodejs@97a77288ce)] [nodejs#12348](nodejs#12348), [[`d75fdd96aa`](nodejs@d75fdd96aa)] [nodejs#10423](nodejs#10423). * Child Process methods accept `Uint8Array` as input [[`627ecee9ed`](nodejs@627ecee9ed)] [nodejs#10653](nodejs#10653). * **Console** * Error events emitted when using `console` methods are now supressed. [[`f18e08d820`](nodejs@f18e08d820)] [nodejs#9744](nodejs#9744). * **Dependencies** * The npm client has been updated to 5.0.0 [[`3c3b36af0f`](nodejs@3c3b36af0f)] [nodejs#12936](nodejs#12936). * V8 has been updated to 5.8 with forward ABI stability to 6.0 [[`60d1aac8d2`](nodejs@60d1aac8d2)] [nodejs#12784](nodejs#12784). * **Domains** * Native `Promise` instances are now `Domain` aware [[`84dabe8373`](nodejs@84dabe8373)] [nodejs#12489](nodejs#12489). * **Errors** * We have started assigning static error codes to errors generated by Node.js. This has been done through multiple commits and is still a work in progress. * **File System** * The utility class `fs.SyncWriteStream` has been deprecated [[`7a55e34ef4`](nodejs@7a55e34ef4)] [nodejs#10467](nodejs#10467). * The deprecated `fs.read()` string interface has been removed [[`3c2a9361ff`](nodejs@3c2a9361ff)] [nodejs#9683](nodejs#9683). * **HTTP** * Improved support for userland implemented Agents [[`90403dd1d0`](nodejs@90403dd1d0)] [nodejs#11567](nodejs#11567). * Outgoing Cookie headers are concatenated into a single string [[`d3480776c7`](nodejs@d3480776c7)] [nodejs#11259](nodejs#11259). * The `httpResponse.writeHeader()` method has been deprecated [[`fb71ba4921`](nodejs@fb71ba4921)] [nodejs#11355](nodejs#11355). * New methods for accessing HTTP headers have been added to `OutgoingMessage` [[`3e6f1032a4`](nodejs@3e6f1032a4)] [nodejs#10805](nodejs#10805). * **Lib** * All deprecation messages have been assigned static identifiers [[`5de3cf099c`](nodejs@5de3cf099c)] [nodejs#10116](nodejs#10116). * The legacy `linkedlist` module has been removed [[`84a23391f6`](nodejs@84a23391f6)] [nodejs#12113](nodejs#12113). * **N-API** * Experimental support for the new N-API API has been added [[`56e881d0b0`](nodejs@56e881d0b0)] [nodejs#11975](nodejs#11975). * **Process** * Process warning output can be redirected to a file using the `--redirect-warnings` command-line argument [[`03e89b3ff2`](nodejs@03e89b3ff2)] [nodejs#10116](nodejs#10116). * Process warnings may now include additional detail [[`dd20e68b0f`](nodejs@dd20e68b0f)] [nodejs#12725](nodejs#12725). * **REPL** * REPL magic mode has been deprecated [[`3f27f02da0`](nodejs@3f27f02da0)] [nodejs#11599](nodejs#11599). * **Src** * `NODE_MODULE_VERSION` has been updated to 57 (nodejs@ec7cbaf266)] [nodejs#12995](nodejs#12995). * Add `--pending-deprecation` command-line argument and `NODE_PENDING_DEPRECATION` environment variable [[`a16b570f8c`](nodejs@a16b570f8c)] [nodejs#11968](nodejs#11968). * The `--debug` command-line argument has been deprecated. Note that using `--debug` will enable the *new* Inspector-based debug protocol as the legacy Debugger protocol previously used by Node.js has been removed. [[`010f864426`](nodejs@010f864426)] [nodejs#12949](nodejs#12949). * Throw when the `-c` and `-e` command-line arguments are used at the same time [[`a5f91ab230`](nodejs@a5f91ab230)] [nodejs#11689](nodejs#11689). * Throw when the `--use-bundled-ca` and `--use-openssl-ca` command-line arguments are used at the same time. [[`8a7db9d4b5`](nodejs@8a7db9d4b5)] [nodejs#12087](nodejs#12087). * **Stream** * `Stream` now supports `destroy()` and `_destroy()` APIs [[`b6e1d22fa6`](nodejs@b6e1d22fa6)] [nodejs#12925](nodejs#12925). * `Stream` now supports the `_final()` API [[`07c7f198db`](nodejs@07c7f198db)] [nodejs#12828](nodejs#12828). * **TLS** * The `rejectUnauthorized` option now defaults to `true` [[`348cc80a3c`](nodejs@348cc80a3c)] [nodejs#5923](nodejs#5923). * The `tls.createSecurePair()` API now emits a runtime deprecation [[`a2ae08999b`](nodejs@a2ae08999b)] [nodejs#11349](nodejs#11349). * A runtime deprecation will now be emitted when `dhparam` is less than 2048 bits [[`d523eb9c40`](nodejs@d523eb9c40)] [nodejs#11447](nodejs#11447). * **URL** * The WHATWG URL implementation is now a fully-supported Node.js API [[`d080ead0f9`](nodejs@d080ead0f9)] [nodejs#12710](nodejs#12710). * **Util** * `Symbol` keys are now displayed by default when using `util.inspect()` [[`5bfd13b81e`](nodejs@5bfd13b81e)] [nodejs#9726](nodejs#9726). * `toJSON` errors will be thrown when formatting `%j` [[`455e6f1dd8`](nodejs@455e6f1dd8)] [nodejs#11708](nodejs#11708). * Convert `inspect.styles` and `inspect.colors` to prototype-less objects [[`aab0d202f8`](nodejs@aab0d202f8)] [nodejs#11624](nodejs#11624). * The new `util.promisify()` API has been added [[`99da8e8e02`](nodejs@99da8e8e02)] [nodejs#12442](nodejs#12442). * **Zlib** * Support `Uint8Array` in Zlib convenience methods [[`91383e47fd`](nodejs@91383e47fd)] [nodejs#12001](nodejs#12001). * Zlib errors now use `RangeError` and `TypeError` consistently [[`b514bd231e`](nodejs@b514bd231e)] [nodejs#11391](nodejs#11391).

* **Async Hooks** * The `async_hooks` module has landed in core [[`4a7233c178`](4a7233c178)] [#12892](#12892). * **Buffer** * Using the `--pending-deprecation` flag will cause Node.js to emit a deprecation warning when using `new Buffer(num)` or `Buffer(num)`. [[`d2d32ea5a2`](d2d32ea5a2)] [#11968](#11968). * `new Buffer(num)` and `Buffer(num)` will zero-fill new `Buffer` instances [[`7eb1b4658e`](7eb1b4658e)] [#12141](#12141). * Many `Buffer` methods now accept `Uint8Array` as input [[`beca3244e2`](beca3244e2)] [#10236](#10236). * **Child Process** * Argument and kill signal validations have been improved [[`97a77288ce`](97a77288ce)] [#12348](#12348), [[`d75fdd96aa`](d75fdd96aa)] [#10423](#10423). * Child Process methods accept `Uint8Array` as input [[`627ecee9ed`](627ecee9ed)] [#10653](#10653). * **Console** * Error events emitted when using `console` methods are now supressed. [[`f18e08d820`](f18e08d820)] [#9744](#9744). * **Dependencies** * The npm client has been updated to 5.0.0 [[`3c3b36af0f`](3c3b36af0f)] [#12936](#12936). * V8 has been updated to 5.8 with forward ABI stability to 6.0 [[`60d1aac8d2`](60d1aac8d2)] [#12784](#12784). * **Domains** * Native `Promise` instances are now `Domain` aware [[`84dabe8373`](84dabe8373)] [#12489](#12489). * **Errors** * We have started assigning static error codes to errors generated by Node.js. This has been done through multiple commits and is still a work in progress. * **File System** * The utility class `fs.SyncWriteStream` has been deprecated [[`7a55e34ef4`](7a55e34ef4)] [#10467](#10467). * The deprecated `fs.read()` string interface has been removed [[`3c2a9361ff`](3c2a9361ff)] [#9683](#9683). * **HTTP** * Improved support for userland implemented Agents [[`90403dd1d0`](90403dd1d0)] [#11567](#11567). * Outgoing Cookie headers are concatenated into a single string [[`d3480776c7`](d3480776c7)] [#11259](#11259). * The `httpResponse.writeHeader()` method has been deprecated [[`fb71ba4921`](fb71ba4921)] [#11355](#11355). * New methods for accessing HTTP headers have been added to `OutgoingMessage` [[`3e6f1032a4`](3e6f1032a4)] [#10805](#10805). * **Lib** * All deprecation messages have been assigned static identifiers [[`5de3cf099c`](5de3cf099c)] [#10116](#10116). * The legacy `linkedlist` module has been removed [[`84a23391f6`](84a23391f6)] [#12113](#12113). * **N-API** * Experimental support for the new N-API API has been added [[`56e881d0b0`](56e881d0b0)] [#11975](#11975). * **Process** * Process warning output can be redirected to a file using the `--redirect-warnings` command-line argument [[`03e89b3ff2`](03e89b3ff2)] [#10116](#10116). * Process warnings may now include additional detail [[`dd20e68b0f`](dd20e68b0f)] [#12725](#12725). * **REPL** * REPL magic mode has been deprecated [[`3f27f02da0`](3f27f02da0)] [#11599](#11599). * **Src** * `NODE_MODULE_VERSION` has been updated to 57 (ec7cbaf266)] [#12995](#12995). * Add `--pending-deprecation` command-line argument and `NODE_PENDING_DEPRECATION` environment variable [[`a16b570f8c`](a16b570f8c)] [#11968](#11968). * The `--debug` command-line argument has been deprecated. Note that using `--debug` will enable the *new* Inspector-based debug protocol as the legacy Debugger protocol previously used by Node.js has been removed. [[`010f864426`](010f864426)] [#12949](#12949). * Throw when the `-c` and `-e` command-line arguments are used at the same time [[`a5f91ab230`](a5f91ab230)] [#11689](#11689). * Throw when the `--use-bundled-ca` and `--use-openssl-ca` command-line arguments are used at the same time. [[`8a7db9d4b5`](8a7db9d4b5)] [#12087](#12087). * **Stream** * `Stream` now supports `destroy()` and `_destroy()` APIs [[`b6e1d22fa6`](b6e1d22fa6)] [#12925](#12925). * `Stream` now supports the `_final()` API [[`07c7f198db`](07c7f198db)] [#12828](#12828). * **TLS** * The `rejectUnauthorized` option now defaults to `true` [[`348cc80a3c`](348cc80a3c)] [#5923](#5923). * The `tls.createSecurePair()` API now emits a runtime deprecation [[`a2ae08999b`](a2ae08999b)] [#11349](#11349). * A runtime deprecation will now be emitted when `dhparam` is less than 2048 bits [[`d523eb9c40`](d523eb9c40)] [#11447](#11447). * **URL** * The WHATWG URL implementation is now a fully-supported Node.js API [[`d080ead0f9`](d080ead0f9)] [#12710](#12710). * **Util** * `Symbol` keys are now displayed by default when using `util.inspect()` [[`5bfd13b81e`](5bfd13b81e)] [#9726](#9726). * `toJSON` errors will be thrown when formatting `%j` [[`455e6f1dd8`](455e6f1dd8)] [#11708](#11708). * Convert `inspect.styles` and `inspect.colors` to prototype-less objects [[`aab0d202f8`](aab0d202f8)] [#11624](#11624). * The new `util.promisify()` API has been added [[`99da8e8e02`](99da8e8e02)] [#12442](#12442). * **Zlib** * Support `Uint8Array` in Zlib convenience methods [[`91383e47fd`](91383e47fd)] [#12001](#12001). * Zlib errors now use `RangeError` and `TypeError` consistently [[`b514bd231e`](b514bd231e)] [#11391](#11391).

jasnell added the semver-minor PRs that contain new features and should be released in the next minor version. label Apr 28, 2017

nodejs-github-bot added doc Issues and PRs related to the documentations. url Issues and PRs related to the legacy built-in url module. labels Apr 28, 2017

jasnell added dont-land-on-v4.x whatwg-url Issues and PRs related to the WHATWG URL implementation. labels Apr 28, 2017

jasnell mentioned this pull request Apr 28, 2017

Backport WHATWG URL to 6.x? nodejs/Release#208

Closed

jasnell added this to the 8.0.0 milestone Apr 28, 2017

Trott reviewed Apr 28, 2017

View reviewed changes

joyeecheung approved these changes Apr 28, 2017

View reviewed changes

TimothyGu reviewed Apr 28, 2017

View reviewed changes

watilde approved these changes Apr 28, 2017

View reviewed changes

cjihrig approved these changes Apr 28, 2017

View reviewed changes

jasnell force-pushed the non-experimental-whatwg-url branch from da52c0b to 671ca55 Compare April 28, 2017 20:20

TimothyGu force-pushed the non-experimental-whatwg-url branch from d7379a9 to 9a2aea8 Compare April 29, 2017 19:12

joyeecheung approved these changes Apr 30, 2017

View reviewed changes

ChALkeR mentioned this pull request May 4, 2017

doc: update experimental status to reflect use #12723

Closed

2 tasks

TimothyGu mentioned this pull request May 25, 2017

Node.js 8.0.0 release announcement nodejs/CTC#135

Closed

gibfahn added the ctc-review label May 28, 2017

gibfahn approved these changes May 28, 2017

View reviewed changes

jasnell added 2 commits May 29, 2017 07:36

doc: graduate WHATWG URL from Experimental

d7aad0d

doc: restructure url.md

7e23f40

jasnell force-pushed the non-experimental-whatwg-url branch from 9a2aea8 to 7e23f40 Compare May 29, 2017 14:36

jasnell closed this May 29, 2017

vsemozhetbyt mentioned this pull request May 29, 2017

doc: fix code examples in url.md #13268

Closed

2 tasks

vsemozhetbyt mentioned this pull request May 29, 2017

doc: fix code examples in url.md #13288

Closed

2 tasks

Trott removed the ctc-review label May 29, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: graduate WHATWG URL from Experimental #12710

doc: graduate WHATWG URL from Experimental #12710

jasnell commented Apr 28, 2017 •

edited

Loading

hiroppy commented Apr 28, 2017

Trott Apr 28, 2017

TimothyGu left a comment

jasnell commented Apr 28, 2017

sam-github commented Apr 28, 2017 •

edited

Loading

jasnell commented Apr 28, 2017

Fishrock123 commented Apr 28, 2017

jasnell commented Apr 28, 2017

TimothyGu commented Apr 29, 2017

joyeecheung left a comment

joyeecheung Apr 30, 2017

TimothyGu May 4, 2017

ChALkeR commented May 4, 2017

jasnell commented May 28, 2017

gibfahn commented May 28, 2017

targos commented May 29, 2017

jasnell commented May 29, 2017

jasnell commented May 29, 2017

doc: graduate WHATWG URL from Experimental #12710

doc: graduate WHATWG URL from Experimental #12710

Conversation

jasnell commented Apr 28, 2017 • edited Loading

Checklist

Affected core subsystem(s)

hiroppy commented Apr 28, 2017

Trott Apr 28, 2017

Choose a reason for hiding this comment

TimothyGu left a comment

Choose a reason for hiding this comment

jasnell commented Apr 28, 2017

sam-github commented Apr 28, 2017 • edited Loading

jasnell commented Apr 28, 2017

Fishrock123 commented Apr 28, 2017

jasnell commented Apr 28, 2017

TimothyGu commented Apr 29, 2017

joyeecheung left a comment

Choose a reason for hiding this comment

joyeecheung Apr 30, 2017

Choose a reason for hiding this comment

TimothyGu May 4, 2017

Choose a reason for hiding this comment

ChALkeR commented May 4, 2017

jasnell commented May 28, 2017

gibfahn commented May 28, 2017

targos commented May 29, 2017

jasnell commented May 29, 2017

jasnell commented May 29, 2017

jasnell commented Apr 28, 2017 •

edited

Loading

sam-github commented Apr 28, 2017 •

edited

Loading