Repository navigation
meta: handling of undocumented endpoint #14679
Description
Activity
I guess a key question is how long it's been "in the wild". If something has only been included in a couple of releases (and not documented) then deprecating/removing it ASAP might be better for users than doing a full deprecation cycle.
Otherwise I don't think it matters whether we meant to expose it or not, given that we treat our code as the definition of our API.
Given that its javascript, its hard to have every single internal property hidden from the user. I think its OK to have undocumented but user-visible properties.
If they are useful, though, they should be documented.
If they aren't useful or we don't want to support them, its not clear whether they have to be documented as a prequel to deprecating them.
Whether we formally doc and deprecate them or not, removing them is semver-major, though I recall at least once we did it without calling it semver because the property had existed for only a couple patch versions and it was deemed worth deleting before any user code started to depend on it.
Reacted by Refael AckermannAnd I agree with @refack, our policy should be documented.
our policy should be documented.
I just re-read https://github.com/nodejs/node/blob/master/COLLABORATOR_GUIDE.md#internal-vs-public-api, It's more explicit than I remembered, but it seems like we don't follow it, as we tend to be more strict...
P.S. all hail
inspector Enble@refack Status? Conclusion?
Closing at the APIs originally discussed have been dealt with.
Recently some undocumented "public" endpoints have been surfaced:
partial list
tls.parseCertString()- tls: move parseCertString to internal #14218, doc, tls: mark parseCertString() as deprecated #14245REPLServer.parseREPLKeyword- repl: deprecate REPLServer.parseREPLKeyword #14223tls.convertNPNProtocols()- tls: remove Next Protocol Negotiation? [rfc] #14602ServerResponse.prototype.writeHeader()- http: docs deprecate ServerResponse.prototype.writeHeader() #11355subprocess.killed- doc: add documentation forkilledproperty of ChildProcess instance #14578IMHO we should have explicit policy for handling these endpoints. Specifically, should they be documented or deprecated, and how. A few discussion points come to mind:
killedproperty of ChildProcess instance #14578, cluster: remove deprecated API #13702)/cc @nodejs/documentation @nodejs/release @nodejs/ctc @nodejs/testing @nodejs/community-committee