diff options
| -rw-r--r-- | doc/api/documentation.md | 10 | ||||
| -rw-r--r-- | 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 be5e7671f8..71e0b49206 100644 --- 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 index 81d30b8abb..e6171bb6c2 100644 --- 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)` |