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

doc: clarify the meaning of legacy status #42269

Merged
merged 11 commits into from Mar 14, 2022
Merged

doc: clarify the meaning of legacy status #42269

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
3323b8a
doc: clarify the meaning of legacy status
RaisinTen Mar 9, 2022
128c438
fixup! Update doc/api/documentation.md
RaisinTen Mar 9, 2022
75c4766
mixup! Update doc/api/url.md
RaisinTen Mar 9, 2022
d437706
fixup! mixup! Update doc/api/url.md
RaisinTen Mar 9, 2022
471d162
fixup! fixup! mixup! Update doc/api/url.md
RaisinTen Mar 9, 2022
e3d9b27
fixup! Update doc/api/deprecations.md
RaisinTen Mar 9, 2022
4273271
doc: clarify the meaning of legacy status
RaisinTen Mar 12, 2022
0334b1c
fixup! Update doc/api/documentation.md
RaisinTen Mar 12, 2022
85ace39
doc: use lowercase for Legacy and Deprecated
RaisinTen Mar 13, 2022
71fa00c
Update doc/api/url.md
RaisinTen Mar 13, 2022
cc7d2dd
Update doc/api/url.md
RaisinTen Mar 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 1 addition & 2 deletions doc/api/deprecations.md
View file
Open in desktop
Expand Up @@ -4,8 +4,7 @@

<!-- type=misc -->

Node.js APIs might be deprecated or given legacy status for any of the
following reasons:
Node.js APIs might be deprecated for any of the following reasons:

* Use of the API is unsafe.
* An improved alternative API is available.
Expand Down
10 changes: 7 additions & 3 deletions doc/api/documentation.md
View file
Open in desktop
Expand Up @@ -40,9 +40,13 @@ The stability indices are as follows:

<!-- separator -->

> Stability: 3 - Legacy. The feature is no longer recommended for use. While it
> likely will not be removed, and is still covered by semantic-versioning
> guarantees, use of the feature should be avoided if possible.
> Stability 3 - Legacy. Although it is unlikely to be removed and is still
> covered by semantic-versioning guarantees, it is no longer actively
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved
> maintained, and other alternatives are available.

Features are marked as Legacy rather than being Deprecated if their use does no
harm, and they are widely relied upon within the npm ecosystem. Bugs found in
Copy link
Member

Choose a reason for hiding this comment

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

though not specified anywhere, IMO, the word ecosystem is qualified with Javascript when we are dealing with a topic that is related to language specification, Node.js when the topic is an API spec, and npm when it is a module spec. So may beNode.js ecosystem is more appropriate here?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@gireeshpunathil I chose to use "npm ecosystem" here because it's used in the description of the "stable" stability index:

node/doc/api/documentation.md

Lines 38 to 39 in 66db116

> Stability: 2 - Stable. Compatibility with the npm ecosystem is a high
> priority.

Perhaps we can change both in a separate pr?

Legacy features are unlikely to be fixed.

Use caution when making use of Experimental features, particularly within
modules. Users may not be aware that experimental features are being used.
Expand Down
11 changes: 10 additions & 1 deletion doc/api/url.md
View file
Open in desktop
Expand Up @@ -1558,11 +1558,20 @@ A `TypeError` is thrown if `urlString` is not a string.

A `URIError` is thrown if the `auth` property is present but cannot be decoded.

Avoid `url.parse()` if you can. Use the WHATWG `URL` API instead.
`url.parse()` uses a lenient, non-standard algorithm for parsing URL
strings. It is prone to security issues such as [host name spoofing][]
and incorrect handling of usernames and passwords.

`url.parse()` is an exception to most of the legacy APIs. Despite its security
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved
concerns, it is not deprecated and it still remains to be a legacy API because
it is:
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved

* faster than the alternative WHATWG `URL` parser
* easier to use with regards to relative URLs than the alternative WHATWG `URL` API
* widely relied upon within the npm ecosystem
RaisinTen marked this conversation as resolved.
Show resolved Hide resolved

Use with caution.

### `url.resolve(from, to)`

<!-- YAML
Expand Down