Node: Deprecation handling for formerly undocumented APIs

[BridgeAR]

Many things in Node core are exposed to the user even though they only exist as implementation detail such as underscore properties. We try to move away from these and add deprecations for backwards compatibility so users are notified about it and to prevent further usage before completely removing the public facing API.
These APIs have not been documented before and most users will likely not know about them if they do not look into the internals actively.

In some cases, there were concerns about adding a runtime deprecation right away instead of using a documentation only deprecation first. Adding a documentation only deprecation for a formerly undocumented "feature" means that other people, who have not known about that API will also stumble upon it. The audience is therefore "bigger" and I fear that people might actually use such an API even though it's only documented as being deprecated.
On top of that I doubt that people who decide to use internal APIs will stop using something if we only add a documentation only deprecation. In fact, I guess they do not check the documentation in such cases. Instead they probably rely on the implementation details they find at a current point of time and see if it just "works".

So I wonder what benefit we have by using a documentation only deprecation. I suggest to always either use a runtime deprecation right away or to keep the API undocumented.

@nodejs/collaborators please weight in so we find a coherent way of dealing with this in the future.

[Trott]

I think there is benefit to documenting an undocumented API and marking it as deprecated in the docs. The benefit is to people who are reading code that uses the undocumented API. They look in the docs and see that the API does exist, but that it's deprecated, so they know they should not use it for new code. Seems ideal to me.

In some cases, we may want to never runtime deprecate. In those cases, a doc-only deprecation to me seems superior to leaving something undocumented.

[mcollina]

I think it is _hard_ to have a blanket rule. I prefer the runtime-deprecation route vs doc-deprecation. I think that doc-deprecations are not really effective in reducing/preventing usage.

[tniessen]

Maybe we should promote the use of --pending-deprecation and also implement it for more documentation-only deprecations.

[jdalton]

I prefer the existing doc -> (major bump) runtime -> (major bump) removal route. I'm not a fan of shortcutting it.

[refack]

Ref: https://github.com/nodejs/node/issues/14679 (the conclusion there is that the policy allows for removal without deprecation, but we never follow that because of ecosystem breakage).

So I wonder what benefit we have by using a documentation only deprecation. I suggest to always either use a runtime deprecation right away or to keep the API undocumented.

IMHO the main problem in keeping things undocumented is that it leaves doubt in the POV of the user. I suggest the following:

1. If there is consensus on benefit (or no consensus on disadvantage) - document.
2. Else-If there is little eco system usage - runtime deprecate
3. Else - doc-deprecate - so that the users are aware that using is not recommended.

[watson]

As a heavy user of undocumented underscore properties my self, I can tell you that documentation probably wouldn't have helped. In many cases it have helped me implement better code because of bugs in core modules that can only be worked around by using the underscore properties (streams anyone?). In other cases it was simply to get access to state not available otherwise.

When I use an underscore property, I use it because it's the only way to achieve a certain thing. The only thing that would make me stop that is if it prints out a deprecation warning. No amount of documentation would have changed this.

If I remember correctly we have previously used runtime deprecations for code that wasn't under node_modules as to not "spam" users with deprecation warnings for code they couldn't directly control. We could use a similar form of soft deprecation for these as well in the first iteration before switching it on for all usage.

[Trott]

It seems like perhaps this should be closed. Feel free to re-open (or leave a comment requesting that it be re-opened) if you disagree. I'm just tidying up and not acting on a super-strong opinion or anything like that.