Skip to content
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

Closed
refack opened this issue Aug 7, 2017 · 7 comments
Closed

meta: handling of undocumented endpoint #14679

refack opened this issue Aug 7, 2017 · 7 comments
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.

Comments

@refack
Copy link
Contributor

refack commented Aug 7, 2017

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

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

@refack refack added discuss Issues opened for discussions and feedbacks. doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project. labels Aug 7, 2017
@gibfahn
Copy link
Member

gibfahn commented Aug 8, 2017

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
Copy link
Contributor

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
Copy link
Contributor

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

@refack
Copy link
Contributor Author

refack commented Aug 10, 2017

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
Copy link
Member

@refack Status? Conclusion?

@Trott Trott removed the discuss Issues opened for discussions and feedbacks. label Mar 11, 2018
@jasnell
Copy link
Member

jasnell commented Aug 11, 2018

Closing at the APIs originally discussed have been dealt with.

@jasnell jasnell closed this as completed Aug 11, 2018
@refack
Copy link
Contributor Author

refack commented Aug 11, 2018

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc Issues and PRs related to the documentations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Development

No branches or pull requests

6 participants