url: docs deprecate legacy url API #22715

jasnell · 2018-09-05T18:35:08Z

It's time to start the deprecation process for the legacy URL API.

Documentation-only deprecation for Node.js 11
Hopefully upgraded to Runtime-deprecation in Node.js 12

Checklist

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

nodejs-github-bot · 2018-09-05T18:35:11Z

@jasnell build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/804/pipeline

targos

The functions should be marked as deprecated in url.md.

refack

👍 on process

jasnell · 2018-09-05T19:02:44Z

@targos ... done!

addaleax

Hopefully upgraded to Runtime-deprecation in Node.js 12

That time frame seems off by a few years?

BridgeAR · 2018-09-05T20:09:20Z

Would it be to early to add this to the pending deprecations? That would allow people who actively opt in to know that it's deprecated even without looking at the docs.

mcollina

LGTM.

TimothyGu

Unfortunately, I see #12682 as a blocker for the deprecation of the legacy URL API. We need to have a story for Express and other modules that still heavily use the legacy API (Express does so through the parseurl wrapper), whether that be a userland module or a Core API, preferably before we start the deprecation proceedings and definitely before we runtime-deprecate the API. Sorry about blocking this.

jasnell · 2018-09-05T21:42:13Z

@TimothyGu, that's precisely why this is a documentation only deprecation.

jasnell · 2018-09-05T21:43:45Z

In other words, I don't think we can actually start moving people through the migration until we start the deprecation because there won't be pressure to actually change

TimothyGu

With the commitment to address #12682 before runtime deprecation, LGTM.

TimothyGu · 2018-09-05T21:45:19Z

doc/api/deprecations.md

+Type: Documentation
+
+The [Legacy URL API][] is deprecated in favor of the newer standardized
+[WHATWG URL][] implementation. This includes uses of `url.format()`,


url.format() should be qualified to not include the overload that takes URL objects.

I'm not sure it should. I added that strictly as a convenience. The intent here is to move people away from the non-standard API and keeping that one variant un-deprecated would not make sense. Folks really should be using the href property on the URL object instead.

TimothyGu · 2018-09-05T21:46:10Z

doc/api/deprecations.md

+
+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`.


Links for the functions and "legacy urlObject" would be nice.

Trott · 2018-09-07T20:16:06Z

doc/api/deprecations.md

+
+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`][].


@jasnell Is it OK with you if I change the text to this?:

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.

(This will also require updating the link reference currently on line 1158 to say WHATWG URL API rather than WHATWG URL.)

Whatever you'd like

PR-URL: #22715 Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Tiancheng "Timothy" Gu <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>

jasnell · 2018-09-07T23:57:57Z

Landed in 922a1b0

PR-URL: nodejs#22765 Refs: nodejs#22715 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>

Fishrock123 · 2018-12-17T23:50:55Z

I do not agree with deprecating url.format() with no suitable replacement: #25099

jasnell · 2018-12-20T15:45:02Z

Please define "suitable replacement" as that is quite subjective. The URL standard does expose ways of creating and formatting a URL that would be relatively trivial to wrap into a url.format() type of utility function is userland. Also note, the deprecation is docs-only, and was signed off by 11 collaborators (5 of whom are TSC). There were no objections prior to the deprecation landing. I see no reason to remove the deprecation for url.format()

nodejs-github-bot added deprecations Issues and PRs related to deprecations. doc Issues and PRs related to the documentations. labels Sep 5, 2018

jasnell added the semver-major PRs that contain breaking changes and should be released in the next major version. label Sep 5, 2018

jasnell requested a review from a team September 5, 2018 18:36

targos requested changes Sep 5, 2018

View reviewed changes

refack approved these changes Sep 5, 2018

View reviewed changes

targos approved these changes Sep 5, 2018

View reviewed changes

vsemozhetbyt approved these changes Sep 5, 2018

View reviewed changes

vsemozhetbyt added the url Issues and PRs related to the legacy built-in url module. label Sep 5, 2018

addaleax approved these changes Sep 5, 2018

View reviewed changes

trivikr approved these changes Sep 5, 2018

View reviewed changes

BridgeAR approved these changes Sep 5, 2018

View reviewed changes

devsnek approved these changes Sep 5, 2018

View reviewed changes

mcollina approved these changes Sep 5, 2018

View reviewed changes

TimothyGu suggested changes Sep 5, 2018

View reviewed changes

TimothyGu approved these changes Sep 5, 2018

View reviewed changes

lpinca approved these changes Sep 6, 2018

View reviewed changes

cjihrig approved these changes Sep 6, 2018

View reviewed changes

url: docs deprecate legacy url API

3a04026

jasnell force-pushed the deprecate-legacy-url branch from 66e8a36 to 3a04026 Compare September 6, 2018 14:45

Trott reviewed Sep 7, 2018

View reviewed changes

Update deprecations.md

86698e0

jasnell closed this Sep 7, 2018

tniessen mentioned this pull request Sep 8, 2018

doc: fix type of DEP0116 #22765

Closed

3 tasks

Trott pushed a commit to Trott/io.js that referenced this pull request Sep 9, 2018

doc: fix type of DEP0116

67ba8ff

PR-URL: nodejs#22765 Refs: nodejs#22715 Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Rich Trott <[email protected]>

kanongil mentioned this pull request Sep 11, 2018

Use WHATWG URL for request.url hapijs/hapi#3822

Merged

Fishrock123 mentioned this pull request Dec 17, 2018

WhatWG URL provides no suitable replacement for url.format() #25099

Closed

trivikr mentioned this pull request Oct 4, 2019

Remove misleading paragraph about the Legacy URL API #29844

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

url: docs deprecate legacy url API #22715

url: docs deprecate legacy url API #22715

jasnell commented Sep 5, 2018

nodejs-github-bot commented Sep 5, 2018

targos left a comment

refack left a comment

jasnell commented Sep 5, 2018

addaleax left a comment

BridgeAR commented Sep 5, 2018

mcollina left a comment

TimothyGu left a comment

jasnell commented Sep 5, 2018

jasnell commented Sep 5, 2018

TimothyGu left a comment

TimothyGu Sep 5, 2018

jasnell Sep 6, 2018

TimothyGu Sep 5, 2018

jasnell Sep 6, 2018

Trott Sep 7, 2018 •

edited

Loading

jasnell Sep 7, 2018

jasnell commented Sep 7, 2018

Fishrock123 commented Dec 17, 2018

jasnell commented Dec 20, 2018

url: docs deprecate legacy url API #22715

url: docs deprecate legacy url API #22715

Conversation

jasnell commented Sep 5, 2018

Checklist

nodejs-github-bot commented Sep 5, 2018

targos left a comment

Choose a reason for hiding this comment

refack left a comment

Choose a reason for hiding this comment

jasnell commented Sep 5, 2018

addaleax left a comment

Choose a reason for hiding this comment

BridgeAR commented Sep 5, 2018

mcollina left a comment

Choose a reason for hiding this comment

TimothyGu left a comment

Choose a reason for hiding this comment

jasnell commented Sep 5, 2018

jasnell commented Sep 5, 2018

TimothyGu left a comment

Choose a reason for hiding this comment

TimothyGu Sep 5, 2018

Choose a reason for hiding this comment

jasnell Sep 6, 2018

Choose a reason for hiding this comment

TimothyGu Sep 5, 2018

Choose a reason for hiding this comment

jasnell Sep 6, 2018

Choose a reason for hiding this comment

Trott Sep 7, 2018 • edited Loading

Choose a reason for hiding this comment

jasnell Sep 7, 2018

Choose a reason for hiding this comment

jasnell commented Sep 7, 2018

Fishrock123 commented Dec 17, 2018

jasnell commented Dec 20, 2018

Trott Sep 7, 2018 •

edited

Loading