From 3603497d1ca80163d7ca6d2ac65902d94289f5c5 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 11 Dec 2018 15:21:09 -0800 Subject: [PATCH 1/2] doc: revise internal vs. public API in Collaborator Guide Make the Collaborator Guide section "Internal vs. Public API" more concise and clear. Remove repetition. Clarify some ambiguity. wordy, repetitive, and somewhat --- COLLABORATOR_GUIDE.md | 68 ++++++++++++++----------------------------- 1 file changed, 22 insertions(+), 46 deletions(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 7f87978debbd66..0c87fcb69eaf08 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -217,52 +217,28 @@ used in other CI test runs (such as `--worker`). ### Internal vs. Public API -Due to the nature of the JavaScript language, it can often be difficult to -establish a clear distinction between which parts of the Node.js implementation -represent the public API Node.js users should assume to be stable and which -are part of the internal implementation details of Node.js itself. A rule of -thumb is to base the determination off what functionality is actually -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 -Node.js API are internal: - -- All functionality exposed via `process.binding(...)` is internal. -- All functionality implemented in `lib/internal/**/*.js` is internal unless it - 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 -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, -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 -difficult and will need to be handled on a case-by-case basis. For instance, if -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) -on how to handle those types of changes. +All functionality in the official Node.js documentation is part of the public +API. Any undocumented object, property, method, argument, behavior, or even is +internal. There are exceptions to this rule. Node.js users have come to rely on +some undocumented behaviors. Collaborators treat many of those undocumented +behaviors as public. + +All undocumented functionality exposed via `process.binding(...)` is internal. + +All undocumented functionality in `lib/internal/**/*.js` is internal. It is +public, though, if it is re-exported by code in `lib/*.js`. + +Non-exported `Symbol` properties and methods are internal. + +Any undocumented object property or method that begins with `_` is internal. + +Any native C/C++ APIs/ABIs requiring the `NODE_WANT_INTERNALS` flag are +internal. + +Sometimes, there is disagreement about whether functionality is internal or +public. In those cases, the TSC makes a determination. + +For undocumented APIs that are public, open a pull request documenting the API. ### Breaking Changes From d0f9d52b2a513d8eb2fa157a56d265ea3c6f420c Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Tue, 11 Dec 2018 16:24:49 -0800 Subject: [PATCH 2/2] fixup! doc: revise internal vs. public API in Collaborator Guide --- COLLABORATOR_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/COLLABORATOR_GUIDE.md b/COLLABORATOR_GUIDE.md index 0c87fcb69eaf08..193591381a108a 100644 --- a/COLLABORATOR_GUIDE.md +++ b/COLLABORATOR_GUIDE.md @@ -218,7 +218,7 @@ used in other CI test runs (such as `--worker`). ### Internal vs. Public API All functionality in the official Node.js documentation is part of the public -API. Any undocumented object, property, method, argument, behavior, or even is +API. Any undocumented object, property, method, argument, behavior, or event is internal. There are exceptions to this rule. Node.js users have come to rely on some undocumented behaviors. Collaborators treat many of those undocumented behaviors as public.