-
Notifications
You must be signed in to change notification settings - Fork 30k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
meta: handling of undocumented endpoint #14679
Comments
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. |
And I agree with @refack, 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 |
@refack Status? Conclusion? |
Closing at the APIs originally discussed have been dealt with. |
Caveat EmptorFTR, quoting from the docs: Lines 262 to 263 in e039524
|
Recently some undocumented "public" endpoints have been surfaced:
partial list
(update from @jasnell on 2018-08-10, this API has been since deprecated)tls.parseCertString()
- tls: move parseCertString to internal #14218, doc, tls: mark parseCertString() as deprecated #14245(update from @jasnell on 2018-08-10, this API has been documented and deprecated)REPLServer.parseREPLKeyword
- repl: deprecate REPLServer.parseREPLKeyword #14223(update from @jasnell on 2018-08-10, this API has been since removed)tls.convertNPNProtocols()
- tls: remove Next Protocol Negotiation? [rfc] #14602(update from @jasnell on 2018-08-10, this API has been since deprecated)ServerResponse.prototype.writeHeader()
- http: docs deprecate ServerResponse.prototype.writeHeader() #11355(update from @jasnell 2018-08-10, this API has been documented)subprocess.killed
- doc: add documentation forkilled
property 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:
killed
property of ChildProcess instance #14578, cluster: remove deprecated API #13702)/cc @nodejs/documentation @nodejs/release @nodejs/ctc @nodejs/testing @nodejs/community-committee
The text was updated successfully, but these errors were encountered: