meta: handling of undocumented endpoint

[refack]

Recently some undocumented "public" endpoints have been surfaced:
_{partial list}

• 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 since deprecated)
• REPLServer.parseREPLKeyword - repl: deprecate REPLServer.parseREPLKeyword #14223 (update from @jasnell on 2018-08-10, this API has been documented and deprecated)
• tls.convertNPNProtocols() - tls: remove Next Protocol Negotiation? [rfc] #14602 (update from @jasnell on 2018-08-10, this API has been since removed)
• ServerResponse.prototype.writeHeader() - http: docs deprecate ServerResponse.prototype.writeHeader() #11355 (update from @jasnell on 2018-08-10, this API has been since deprecated)
• subprocess.killed - doc: add documentation for killed property of ChildProcess instance #14578 (update from @jasnell 2018-08-10, this API has been documented)

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

1. semverity - can these endpoints be "doc-only" deprecated immediately (considered semver-patch)
2. usefulness - should there be a standard process to assess their use (Gzemnid/GitHub search/google/SO/twitter survey)?
3. "sensitivity" - will documenting/deprecating them generate any harm (doc: add documentation for killed property of ChildProcess instance #14578, cluster: remove deprecated API #13702)

/cc @nodejs/documentation @nodejs/release @nodejs/ctc @nodejs/testing @nodejs/community-committee

[gibfahn]

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.

[sam-github]

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.

[sam-github]

And I agree with @refack, our policy should be documented.

[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 inspector Enble}

[bnoordhuis]

@refack Status? Conclusion?

[jasnell]

Closing at the APIs originally discussed have been dealt with.

[refack]

Caveat Emptor

FTR, quoting from the docs:

node/COLLABORATOR_GUIDE.md

Lines 262 to 263 in e039524

	- Any object, property, method, argument, behavior, or event not documented in
	the Node.js documentation is internal.