From 3323b8a24fc593d004be83b8cbd059a845de9cf7 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 20:08:00 +0530 Subject: [PATCH 01/11] 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)` From 128c4382d8d59f50b9dfb12ccde093dac87f8cc2 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 20:36:14 +0530 Subject: [PATCH 02/11] fixup! Update doc/api/documentation.md Co-authored-by: Rich Trott --- doc/api/documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 7862e75988b26b..b1dc181be602cd 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -43,7 +43,7 @@ The stability indices are as follows: > 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. +> recommended as it is 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. From 75c4766b34cc14982af67c71d3d4d84e33cc4c96 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 20:52:23 +0530 Subject: [PATCH 03/11] mixup! Update doc/api/url.md Co-authored-by: Rich Trott --- doc/api/url.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index 929e9dcd25544e..ee3615df63ab29 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1558,12 +1558,10 @@ 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 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. +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.resolve(from, to)` From d437706c90b72ed7e1f7dca3f56f102b875dc520 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 21:01:50 +0530 Subject: [PATCH 04/11] fixup! mixup! Update doc/api/url.md Signed-off-by: Darshan Sen --- doc/api/deprecations.md | 3 ++- doc/api/documentation.md | 7 +++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index c4797d63519b82..5d85140aa2f37e 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4,7 +4,8 @@ -Node.js APIs might be deprecated for any of the following reasons: +Node.js APIs might be deprecated or given the legacy status for any of the +following reasons: * Use of the API is unsafe. * An improved alternative API is available. diff --git a/doc/api/documentation.md b/doc/api/documentation.md index b1dc181be602cd..18b9bc679456b8 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -40,10 +40,9 @@ The stability indices are as follows: -> 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 is not officially supported by the project. +> 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. Use caution when making use of Experimental features, particularly within modules. Users may not be aware that experimental features are being used. From 471d162ad9cc4cf5367c79f47e58f782c118b409 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 21:02:48 +0530 Subject: [PATCH 05/11] fixup! fixup! mixup! Update doc/api/url.md Signed-off-by: Darshan Sen --- doc/api/url.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/url.md b/doc/api/url.md index ee3615df63ab29..bd26530cceff1d 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1558,7 +1558,7 @@ 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. +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. From e3d9b27e26a901c839294e5dc84bd6a514eced5e Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Wed, 9 Mar 2022 21:11:07 +0530 Subject: [PATCH 06/11] fixup! Update doc/api/deprecations.md Co-authored-by: Jordan Harband --- doc/api/deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 5d85140aa2f37e..acf5904c7aea6f 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4,7 +4,7 @@ -Node.js APIs might be deprecated or given the legacy status for any of the +Node.js APIs might be deprecated or given legacy status for any of the following reasons: * Use of the API is unsafe. From 427327131d8f409b22292f65c3d73accf326b500 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Sat, 12 Mar 2022 18:03:11 +0530 Subject: [PATCH 07/11] doc: clarify the meaning of legacy status Signed-off-by: Darshan Sen --- doc/api/deprecations.md | 3 +-- doc/api/documentation.md | 10 +++++++--- doc/api/url.md | 11 ++++++++++- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index acf5904c7aea6f..c4797d63519b82 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -4,8 +4,7 @@ -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. diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 18b9bc679456b8..4468c52f60941a 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 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 +> 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 bd26530cceff1d..e192e01804c9cf 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -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 +concerns, it is not deprecated and it still remains to be a legacy API 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)` -> Stability 3 - Legacy. Although it is unlikely to be removed and is still -> covered by semantic-versioning guarantees, it is no longer actively +> 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 From 85ace39d8e1166630babb75b22a4e0955b996d76 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Sun, 13 Mar 2022 12:10:32 +0530 Subject: [PATCH 09/11] doc: use lowercase for Legacy and Deprecated Signed-off-by: Darshan Sen --- doc/api/documentation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index 7cd06cdbe418ef..71e0b49206e23c 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -44,9 +44,9 @@ The stability indices are as follows: > 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 +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. +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. From 71fa00cc60f25381102c6f6c875e6b91a5397fa3 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Sun, 13 Mar 2022 12:13:27 +0530 Subject: [PATCH 10/11] Update doc/api/url.md Co-authored-by: Rich Trott --- doc/api/url.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index e192e01804c9cf..b9e0df31869543 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1563,8 +1563,7 @@ 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 not deprecated and it still remains to be a legacy API because -it is: +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 From cc7d2dd283359b67a08d62dccae9bd4990c325c3 Mon Sep 17 00:00:00 2001 From: Darshan Sen Date: Sun, 13 Mar 2022 20:17:54 +0530 Subject: [PATCH 11/11] Update doc/api/url.md Co-authored-by: Rich Trott --- doc/api/url.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/api/url.md b/doc/api/url.md index b9e0df31869543..0930778fcd1f40 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -1565,9 +1565,9 @@ 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 +* 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.