You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Acceptance of changes made to the legacy APIs #42230
I think "legacy" means "the project does not intend to strategically spend a lot of time adding features to this". If people want to contribute improvements to usability or in general as long as it doesn't make maintenance harder I think that's fair game?
Reading these I get the feeling that the project explicitly discourages uses of these APIs.
Right - why do you think that conflicts? We can recommend one API (WHATWG URL) while supporting two (WHATWG URL and url) and still improving both though strategically only investing in one can't we?
Usually legacy APIs are so because we can't improve them without breaking the ecosystem. This would rule out most semver-major changes, however bugfixes and semver-minor could be accepted.
Reacted by Benjamin Gruenbaum, Tobias Nießen, Rich Trott, Jordan Harband, F. Hinkelmann, Anna Henningsen and Michael Dawson
I think they conflict because on the one hand we want folks to migrate to the better API while on the other, we are still giving folks reason to stay on the broken API.
We can recommend one API (WHATWG URL) while supporting two (WHATWG URL and url) and still improving both though strategically only investing in one can't we?
I believe that would have been okay if the document said "not actively supported" instead of "discouraged".
Usually legacy APIs are so because we can't improve them without breaking the ecosystem. This would rule out most semver-major changes, however bugfixes and semver-minor could be accepted.
But isn't that true for stable APIs too? What's the point of labelling the API as legacy if we still treat it as a stable API? Also, instead of applying fixes / semver-minor changes to an API that is inherently broken and unsafe to use, won't it be easier for folks to just move to the recommended API?
But isn't that true for stable APIs too? What's the point of labelling the API as legacy if we still treat it as a stable API?
Basically, I've always read it as an indication that this API should not be adopted in new project since Node is not going to strategically invest a lot of time on it.
If there is an API we'll never remove but want people to really not use it's usually "forever deprecated" like new Buffer and friends.
> Stability: 0 - Deprecated. The feature may emit warnings. Backward
> compatibility is not guaranteed.
doesn't say that the deprecated APIs will never be removed. Only the legacy status says that. In fact, the third stage of our deprecation policy, "End-of-Life", explicitly states that the API is/will be removed -
But isn't that true for stable APIs too? What's the point of labelling the API as legacy if we still treat it as a stable API? Also, instead of applying fixes / semver-minor changes to an API that is inherently broken and unsafe to use, won't it be easier for folks to just move to the recommended API?
Unfortunately that's not easy at all. Usually those legacy APIs are used in very old modules that have all the quirks figured out. Changing it in 3-4-5 level deep is very hard.
Also, are you trying to say that it is easier to make the needed changes to the parser in Node.js than to the code that uses the legacy API inside the older module? If that's so, I was wondering if the migration strategy I stated in #42196 (comment) sounds practical:
"We'll gradually make changes to url.parse() to make it feel more like WHATWG URL. Since the differences between the two includes many breaking changes, we'll land those too, so that it's easier for users to adapt to WHATWG URL bit by bit than to ask them to make changes to their code to be WHATWG URL-friendly all at once."
Yes, it does talk about making semver-major changes but if we do them gradually, it should be helpful for users to migrate. Not sure why we are ruling out semver-major changes for legacy APIs.
What's the point of labelling the API as legacy if we still treat it as a stable API?
The stability labels aren't about differences in our process, although that can be part of it. But the labels are for users, not us. The label says "Don't use this in new code." It does not require us to have a different maintenance process.
The stability labels aren't about differences in our process, although that can be part of it. But the labels are for users, not us.
I thought these labels were supposed to convey to the users how we maintain these APIs, so it is a result of us having different maintenance processes for each.
The label says "Don't use this in new code."
It doesn't specifically say "new code", so it stands for both new and old code.
Should we accept changes made to the legacy APIs? If so, what kinds of changes should we accept?
I think it's useful to ask the question like this:
Should we make an effort to intentionally preserve security vulnerabilities and other bugs in Legacy APIs so that it inflicts pain on end users when that user is using the API, even if it is in a transitive dependency?
EDIT: Just to make it 100% clear that I'm NOT advocating the pro-bugs pro-user-pain perspective, I'll mention that I definitely think we should allow fixes. I mean, obviously. But just in case it wasn't obvious.
Bug fixes that don't break backwards compat or introduce significant regressions: Yes if there are people who want to work on it.
New features, breaking changes: No.
In the case of something like url.parse, I would view making it act more like the WHATWG parser as falling under the New Feature category. That is, url.parse was never meant to be compliant with WHATWG so changing it to start being compliant qualifies as new function and new feature. Making it do so just signals that folks are fine to keep using the API in new things which is counter to the purpose of marking it as Legacy.
I don't think we should "discourage" folks from using it
Unless there are very real reasons folks shouldn't be using it and should be using the new one, which in the case of url.parse() there are.
Won't that be applicable the other way round too? The points in #42232 (comment) are some reasons to discourage the uses of the newer API and use the legacy API instead. I don't think we should discourage/encourage the usage of any of these. In stead, we can make it very clear in the docs that the project does not officially support one of the APIs and then let the users decide if they want to use it or not.
And if we choose to discourage uses of the legacy API (which we should talk about in #42232), I think we should do it through a runtime warning because it communicates the message better. We don't have to go ahead with the End-of-Life deprecation though (which is what's happening with the Buffer c'tor).
But again, those reasons aren't enough to force folks off url.parse()
Then saying "uses in newer code is discouraged" sounds more fitting?
Maybe we could get the habit of running CITGM for any changes to a legacy API, and withdraw the PR if that makes any package fail. Not sure if it needs to be a documented process, but that could help having revert PRs (e.g. #42280).
Activity
benjamingr commentedon Mar 6, 2022
I think "legacy" means "the project does not intend to strategically spend a lot of time adding features to this". If people want to contribute improvements to usability or in general as long as it doesn't make maintenance harder I think that's fair game?
RaisinTen commentedon Mar 6, 2022
If the project accepts changes that improve the usability of a legacy API, it conflicts with what the project currently states -
node/doc/api/documentation.md
Lines 43 to 45 in 3d4f3ca
node/doc/api/url.md
Lines 1562 to 1566 in 3d4f3ca
Reading these I get the feeling that the project explicitly discourages uses of these APIs.
benjamingr commentedon Mar 6, 2022
Right - why do you think that conflicts? We can recommend one API (WHATWG URL) while supporting two (WHATWG URL and url) and still improving both though strategically only investing in one can't we?
mcollina commentedon Mar 6, 2022
Usually legacy APIs are so because we can't improve them without breaking the ecosystem. This would rule out most semver-major changes, however bugfixes and semver-minor could be accepted.
RaisinTen commentedon Mar 6, 2022
I think they conflict because on the one hand we want folks to migrate to the better API while on the other, we are still giving folks reason to stay on the broken API.
I believe that would have been okay if the document said "not actively supported" instead of "discouraged".
But isn't that true for stable APIs too? What's the point of labelling the API as legacy if we still treat it as a stable API? Also, instead of applying fixes / semver-minor changes to an API that is inherently broken and unsafe to use, won't it be easier for folks to just move to the recommended API?
benjamingr commentedon Mar 6, 2022
Basically, I've always read it as an indication that this API should not be adopted in new project since Node is not going to strategically invest a lot of time on it.
If there is an API we'll never remove but want people to really not use it's usually "forever deprecated" like
new Bufferand friends.targos commentedon Mar 6, 2022
I thought this was the point the Legacy status. Basically a forever doc-only deprecation.
RaisinTen commentedon Mar 6, 2022
node/doc/api/documentation.md
Lines 26 to 27 in 3d4f3ca
node/doc/api/deprecations.md
Lines 33 to 34 in 3d4f3ca
Documentation-only deprecation is different -
node/doc/api/deprecations.md
Lines 19 to 26 in 3d4f3ca
mcollina commentedon Mar 6, 2022
Unfortunately that's not easy at all. Usually those legacy APIs are used in very old modules that have all the quirks figured out. Changing it in 3-4-5 level deep is very hard.
RaisinTen commentedon Mar 6, 2022
To make it easier for users, would it be reasonable to write a guide like we did in https://nodejs.org/en/docs/guides/buffer-constructor-deprecation/?
Also, are you trying to say that it is easier to make the needed changes to the parser in Node.js than to the code that uses the legacy API inside the older module? If that's so, I was wondering if the migration strategy I stated in #42196 (comment) sounds practical:
Yes, it does talk about making semver-major changes but if we do them gradually, it should be helpful for users to migrate. Not sure why we are ruling out semver-major changes for legacy APIs.
Trott commentedon Mar 6, 2022
The stability labels aren't about differences in our process, although that can be part of it. But the labels are for users, not us. The label says "Don't use this in new code." It does not require us to have a different maintenance process.
Trott commentedon Mar 6, 2022
Yes.
Changes that improve the API without causing widespread breakage for users and that do not substantially increase our maintenance burden.
RaisinTen commentedon Mar 6, 2022
I thought these labels were supposed to convey to the users how we maintain these APIs, so it is a result of us having different maintenance processes for each.
It doesn't specifically say "new code", so it stands for both new and old code.
Trott commentedon Mar 6, 2022
I think it's useful to ask the question like this:
Should we make an effort to intentionally preserve security vulnerabilities and other bugs in Legacy APIs so that it inflicts pain on end users when that user is using the API, even if it is in a transitive dependency?
EDIT: Just to make it 100% clear that I'm NOT advocating the pro-bugs pro-user-pain perspective, I'll mention that I definitely think we should allow fixes. I mean, obviously. But just in case it wasn't obvious.
jasnell commentedon Mar 6, 2022
Bug fixes that don't break backwards compat or introduce significant regressions: Yes if there are people who want to work on it.
New features, breaking changes: No.
In the case of something like url.parse, I would view making it act more like the WHATWG parser as falling under the New Feature category. That is, url.parse was never meant to be compliant with WHATWG so changing it to start being compliant qualifies as new function and new feature. Making it do so just signals that folks are fine to keep using the API in new things which is counter to the purpose of marking it as Legacy.
18 remaining items
RaisinTen commentedon Mar 8, 2022
Won't that be applicable the other way round too? The points in #42232 (comment) are some reasons to discourage the uses of the newer API and use the legacy API instead. I don't think we should discourage/encourage the usage of any of these. In stead, we can make it very clear in the docs that the project does not officially support one of the APIs and then let the users decide if they want to use it or not.
And if we choose to discourage uses of the legacy API (which we should talk about in #42232), I think we should do it through a runtime warning because it communicates the message better. We don't have to go ahead with the End-of-Life deprecation though (which is what's happening with the Buffer c'tor).
Then saying "uses in newer code is discouraged" sounds more fitting?
doc: clarify the meaning of legacy status
RaisinTen commentedon Mar 9, 2022
PR: #42269
aduh95 commentedon Mar 10, 2022
Maybe we could get the habit of running CITGM for any changes to a legacy API, and withdraw the PR if that makes any package fail. Not sure if it needs to be a documented process, but that could help having revert PRs (e.g. #42280).
RaisinTen commentedon Mar 10, 2022
Legacy APIs in particular or all stable APIs (which includes legacy APIs because they are maintained in the same way) in general?
ljharb commentedon Mar 10, 2022
Seems like something we’d want to do on any PR.
targos commentedon Mar 10, 2022
It's something we'd want to do if it didn't take many hours to run and many minutes, if not hours, to analyze the results.
doc: clarify the meaning of legacy status
doc: clarify the meaning of legacy status
doc: clarify the meaning of legacy status
doc: clarify the meaning of legacy status
doc: clarify the meaning of legacy status