Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

url: docs deprecate legacy url API #22715

Closed
wants to merge 2 commits into from
Closed

url: docs deprecate legacy url API #22715

wants to merge 2 commits into from

Conversation

jasnell
Copy link
Member

@jasnell jasnell commented Sep 5, 2018

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
Copy link
Collaborator

@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

@nodejs-github-bot nodejs-github-bot added deprecations Issues and PRs related to deprecations. doc Issues and PRs related to the documentations. labels Sep 5, 2018
@jasnell jasnell added the semver-major PRs that contain breaking changes and should be released in the next major version. label Sep 5, 2018
@jasnell jasnell requested a review from a team September 5, 2018 18:36
targos
targos requested changes Sep 5, 2018
View reviewed changes
Copy link
Member

@targos targos left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

refack
refack approved these changes Sep 5, 2018
View reviewed changes
Copy link
Contributor

@refack refack left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 on process

@jasnell
Copy link
Member Author

jasnell commented Sep 5, 2018

@targos ... done!

@vsemozhetbyt vsemozhetbyt added the url Issues and PRs related to the legacy built-in url module. label Sep 5, 2018
addaleax
addaleax approved these changes Sep 5, 2018
View reviewed changes
Copy link
Member

@addaleax addaleax left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hopefully upgraded to Runtime-deprecation in Node.js 12

That time frame seems off by a few years?

@BridgeAR
Copy link
Member

BridgeAR commented Sep 5, 2018

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
mcollina approved these changes Sep 5, 2018
View reviewed changes
Copy link
Member

@mcollina mcollina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM.

TimothyGu
TimothyGu suggested changes Sep 5, 2018
View reviewed changes
Copy link
Member

@TimothyGu TimothyGu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Member Author

jasnell commented Sep 5, 2018

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

@jasnell
Copy link
Member Author

jasnell commented Sep 5, 2018

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
TimothyGu approved these changes Sep 5, 2018
View reviewed changes
Copy link
Member

@TimothyGu TimothyGu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

doc/api/deprecations.md Outdated
Type: Documentation

The [Legacy URL API][] is deprecated in favor of the newer standardized
[WHATWG URL][] implementation. This includes uses of `url.format()`,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

doc/api/deprecations.md Outdated

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`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added :-)

Trott
Trott reviewed Sep 7, 2018
View reviewed changes
doc/api/deprecations.md Outdated

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`][].
Copy link
Member

@Trott Trott Sep 7, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whatever you'd like

jasnell added a commit that referenced this pull request Sep 7, 2018
@jasnell
url: docs deprecate legacy url API
922a1b0 
PR-URL: #22715
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
@jasnell
Copy link
Member Author

jasnell commented Sep 7, 2018

Landed in 922a1b0

@jasnell jasnell closed this Sep 7, 2018
@tniessen tniessen mentioned this pull request Sep 8, 2018
Closed
3 tasks
Trott pushed a commit to Trott/io.js that referenced this pull request Sep 9, 2018
@tniessen @Trott
doc: fix type of DEP0116
67ba8ff 
PR-URL: nodejs#22765
Refs: nodejs#22715
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
@kanongil kanongil mentioned this pull request Sep 11, 2018
Merged
@Fishrock123 Fishrock123 mentioned this pull request Dec 17, 2018
Closed
@Fishrock123
Copy link
Contributor

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

@jasnell
Copy link
Member Author

jasnell commented Dec 20, 2018

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()

@trivikr trivikr mentioned this pull request Oct 4, 2019
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Trott Trott Trott left review comments

@trivikr trivikr trivikr approved these changes

@vsemozhetbyt vsemozhetbyt vsemozhetbyt approved these changes

@BridgeAR BridgeAR BridgeAR approved these changes

@devsnek devsnek devsnek approved these changes

@cjihrig cjihrig cjihrig approved these changes

@targos targos targos approved these changes

@TimothyGu TimothyGu TimothyGu approved these changes

@lpinca lpinca lpinca approved these changes

@addaleax addaleax addaleax approved these changes

@refack refack refack approved these changes

@mcollina mcollina mcollina approved these changes

Assignees
No one assigned
Labels
deprecations Issues and PRs related to deprecations. doc Issues and PRs related to the documentations. semver-major PRs that contain breaking changes and should be released in the next major version. url Issues and PRs related to the legacy built-in url module.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.