From bfa9b88a760a8ea45a105fbc6e0224edb96c119e Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Mon, 14 Mar 2022 10:40:08 +0530 Subject: [PATCH] doc: clarify the meaning of legacy status MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes: https://github.com/nodejs/node/issues/42230 Fixes: https://github.com/nodejs/node/issues/42232 Signed-off-by: Darshan Sen PR-URL: https://github.com/nodejs/node/pull/42269 Reviewed-By: Rich Trott Reviewed-By: James M Snell Reviewed-By: Michaël Zasso Reviewed-By: Mestery Reviewed-By: Luigi Pinca Reviewed-By: Mohammed Keyvanzadeh Reviewed-By: Tobias Nießen Reviewed-By: Gireesh Punathil Reviewed-By: Matteo Collina --- doc/api/documentation.md | 10 +++++++--- doc/api/url.md | 17 ++++++++++++----- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index be5e7671f8d18c..71e0b49206e23c 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -40,9 +40,13 @@ The stability indices are as follows: -> 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. +> Stability 3 - Legacy. Although this feature is unlikely to be removed and is +> still covered by semantic-versioning guarantees, it is no longer actively +> 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 +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. diff --git a/doc/api/url.md b/doc/api/url.md index 36355493d3888a..27bb6ade0900f6 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1559,11 +1559,18 @@ A `TypeError` is thrown if `urlString` is not a string. A `URIError` is thrown if the `auth` property is present but cannot be decoded. -Use of the legacy `url.parse()` method is discouraged. Users should -use the WHATWG `URL` API. Because the `url.parse()` method uses a -lenient, non-standard algorithm for parsing URL strings, security -issues can be introduced. Specifically, issues with [host name spoofing][] and -incorrect handling of usernames and passwords have been identified. +`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 +concerns, it is legacy and not deprecated because it is: + +* 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. + +Use with caution. ### `url.resolve(from, to)`