doc: clarify the meaning of legacy status

Fixes: nodejs#42230 Fixes: nodejs#42232 Signed-off-by: Darshan Sen <[email protected]> PR-URL: nodejs#42269 Reviewed-By: Rich Trott <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Michaël Zasso <[email protected]> Reviewed-By: Mestery <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Mohammed Keyvanzadeh <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Gireesh Punathil <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
danielleadams · Apr 21, 2022 · 90643ee · 90643ee
1 parent ceb8621
commit 90643ee
Show file tree

Hide file tree

Showing 2 changed files with 19 additions and 8 deletions.
diff --git a/doc/api/documentation.md b/doc/api/documentation.md
@@ -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.
+> 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
@@ -1535,11 +1535,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)`