Acceptance of changes made to the legacy APIs

[RaisinTen]

Should we accept changes made to the legacy APIs? If so, what kinds of changes should we accept?

For reference, this came up when we were discussing about whether we should accept a change made to the legacy url.parse() API in #42196.

cc @nodejs/tsc

[benjamingr]

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]

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

  	> 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.

• node/doc/api/url.md

  Lines 1562 to 1566 in 3d4f3ca

  	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.

Reading these I get the feeling that the project explicitly discourages uses of these APIs.

[benjamingr]

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?

[mcollina]

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]

Right - why do you think that conflicts?

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?

[benjamingr]

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.

[targos]

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.

I thought this was the point the Legacy status. Basically a forever doc-only deprecation.

[RaisinTen]

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.

node/doc/api/documentation.md

Lines 26 to 27 in 3d4f3ca

	> 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 -

node/doc/api/deprecations.md

Lines 33 to 34 in 3d4f3ca

	An End-of-Life deprecation is used when functionality is or will soon be removed
	from Node.js.

.

I thought this was the point the Legacy status. Basically a forever doc-only deprecation.

Documentation-only deprecation is different -

node/doc/api/deprecations.md

Lines 19 to 26 in 3d4f3ca

	A Documentation-only deprecation is one that is expressed only within the
	Node.js API docs. These generate no side-effects while running Node.js.
	Some Documentation-only deprecations trigger a runtime warning when launched
	with [`--pending-deprecation`][] flag (or its alternative,
	`NODE_PENDING_DEPRECATION=1` environment variable), similarly to Runtime
	deprecations below. Documentation-only deprecations that support that flag
	are explicitly labeled as such in the
	[list of Deprecated APIs](#list-of-deprecated-apis).

. It only applies for APIs we really want to deprecate, which is assigned a stability of 0, unlike legacy status, which is assigned a stability of 3.

[mcollina]

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.

[RaisinTen]

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:

"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.

[Trott]

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.

[Trott]

Should we accept changes made to the legacy APIs?

Yes.

If so, what kinds of changes should we accept?

Changes that improve the API without causing widespread breakage for users and that do not substantially increase our maintenance burden.

[RaisinTen]

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.

[Trott]

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.}

[jasnell]

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.