1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: revise internal vs. public API in Collaborator Guide

Browse Source 
Make the Collaborator Guide section "Internal vs. Public API" more
concise and clear. Remove repetition. Clarify some ambiguity.
wordy, repetitive, and somewhat

PR-URL: https://github.com/nodejs/node/pull/24975
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
This commit is contained in:
Rich Trott 2018-12-11 15:21:09 -08:00
parent 450ab14d4b
commit 9f37f9c439
1 changed files with 16 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
COLLABORATOR_GUIDE.md
View File

@ -217,52 +217,28 @@ used in other CI test runs (such as `--worker`).
### Internal vs. Public API ### Internal vs. Public API
Due to the nature of the JavaScript language, it can often be difficult to All functionality in the official Node.js documentation is part of the public
establish a clear distinction between which parts of the Node.js implementation API. Any undocumented object, property, method, argument, behavior, or event is
represent the public API Node.js users should assume to be stable and which internal. There are exceptions to this rule. Node.js users have come to rely on
are part of the internal implementation details of Node.js itself. A rule of some undocumented behaviors. Collaborators treat many of those undocumented
thumb is to base the determination off what functionality is actually behaviors as public.
documented in the official Node.js API documentation. However, it has been
repeatedly demonstrated that either the documentation does not completely cover
implemented behavior or that Node.js users have come to rely heavily on
undocumented aspects of the Node.js implementation.
The following general rules should be followed to determine which aspects of the All undocumented functionality exposed via `process.binding(...)` is internal.
Node.js API are internal:
- All functionality exposed via `process.binding(...)` is internal. All undocumented functionality in `lib/internal/**/*.js` is internal. It is
- All functionality implemented in `lib/internal/**/*.js` is internal unless it public, though, if it is re-exported by code in `lib/*.js`.
is re-exported by code in `lib/*.js` or documented as part of the Node.js
Public API.
- Any object property or method whose key is a non-exported `Symbol` is an
internal property.
- Any object property or method whose key begins with the underscore `_` prefix
is internal unless it is documented as part of the Node.js Public API.
- Any object, property, method, argument, behavior, or event not documented in
the Node.js documentation is internal.
- Any native C/C++ APIs/ABIs exported by the Node.js `*.h` header files that
are hidden behind the `NODE_WANT_INTERNALS` flag are internal.
Exceptions can be made if use or behavior of a given internal API can be Non-exported `Symbol` properties and methods are internal.
demonstrated to be sufficiently relied upon by the Node.js ecosystem such that
any changes would cause too much breakage. The threshold for what qualifies as
too much breakage is to be decided on a case-by-case basis by the TSC.
If it is determined that a currently undocumented object, property, method, Any undocumented object property or method that begins with `_` is internal.
argument, or event *should* be documented, then a pull request adding the
documentation is required in order for it to be considered part of the public
API.
Making a determination about whether something *should* be documented can be Any native C/C++ APIs/ABIs requiring the `NODE_WANT_INTERNALS` flag are
difficult and will need to be handled on a case-by-case basis. For instance, if internal.
one documented API cannot be used successfully without the use of a second
*currently undocumented* API, then the second API *should* be documented. If
using an API in a manner currently undocumented achieves a particular useful
result, a decision will need to be made whether or not that falls within the
supported scope of that API; and if it does, it should be documented.
See [Breaking Changes to Internal Elements](#breaking-changes-to-internal-elements) Sometimes, there is disagreement about whether functionality is internal or
on how to handle those types of changes. public. In those cases, the TSC makes a determination.
For undocumented APIs that are public, open a pull request documenting the API.
### Breaking Changes ### Breaking Changes