From 3323b8a24fc593d004be83b8cbd059a845de9cf7 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 20:08:00 +0530 Subject: [PATCH] doc: clarify the meaning of legacy status Fixes: https://github.com/nodejs/node/issues/42230 Fixes: https://github.com/nodejs/node/issues/42232 Signed-off-by: Darshan Sen --- doc/api/documentation.md | 7 ++++--- doc/api/url.md | 11 ++++++----- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index be5e7671f8d18c..7862e75988b26b 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -40,9 +40,10 @@ 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. It is the same as a forever Documentation-only +> deprecation. While it likely will not be removed, and is still +> covered by semantic-versioning guarantees, use of the feature is no longer +> recommended as it not officially supported by the project. 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 3fa589397f77d6..929e9dcd25544e 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1558,11 +1558,12 @@ 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. +Use of the legacy `url.parse()` method is not encouraged as it is not officially +supported by the project. Users are recommended to use the WHATWG `URL` API +instead. 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.resolve(from, to)`