Skip to content

Commit 877f8a0

Browse files
TrottBethGriggs
authored andcommitted
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 PR-URL: #24975 Reviewed-By: Richard Lau <riclau@uk.ibm.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
1 parent f0bcacd commit 877f8a0

File tree

1 file changed

+22
-46
lines changed

1 file changed

+22
-46
lines changed

COLLABORATOR_GUIDE.md

+22-46
Original file line numberDiff line numberDiff line change
@@ -217,52 +217,28 @@ used in other CI test runs (such as `--worker`).
217217

218218
### Internal vs. Public API
219219

220-
Due to the nature of the JavaScript language, it can often be difficult to
221-
establish a clear distinction between which parts of the Node.js implementation
222-
represent the public API Node.js users should assume to be stable and which
223-
are part of the internal implementation details of Node.js itself. A rule of
224-
thumb is to base the determination off what functionality is actually
225-
documented in the official Node.js API documentation. However, it has been
226-
repeatedly demonstrated that either the documentation does not completely cover
227-
implemented behavior or that Node.js users have come to rely heavily on
228-
undocumented aspects of the Node.js implementation.
229-
230-
The following general rules should be followed to determine which aspects of the
231-
Node.js API are internal:
232-
233-
- All functionality exposed via `process.binding(...)` is internal.
234-
- All functionality implemented in `lib/internal/**/*.js` is internal unless it
235-
is re-exported by code in `lib/*.js` or documented as part of the Node.js
236-
Public API.
237-
- Any object property or method whose key is a non-exported `Symbol` is an
238-
internal property.
239-
- Any object property or method whose key begins with the underscore `_` prefix
240-
is internal unless it is documented as part of the Node.js Public API.
241-
- Any object, property, method, argument, behavior, or event not documented in
242-
the Node.js documentation is internal.
243-
- Any native C/C++ APIs/ABIs exported by the Node.js `*.h` header files that
244-
are hidden behind the `NODE_WANT_INTERNALS` flag are internal.
245-
246-
Exceptions can be made if use or behavior of a given internal API can be
247-
demonstrated to be sufficiently relied upon by the Node.js ecosystem such that
248-
any changes would cause too much breakage. The threshold for what qualifies as
249-
too much breakage is to be decided on a case-by-case basis by the TSC.
250-
251-
If it is determined that a currently undocumented object, property, method,
252-
argument, or event *should* be documented, then a pull request adding the
253-
documentation is required in order for it to be considered part of the public
254-
API.
255-
256-
Making a determination about whether something *should* be documented can be
257-
difficult and will need to be handled on a case-by-case basis. For instance, if
258-
one documented API cannot be used successfully without the use of a second
259-
*currently undocumented* API, then the second API *should* be documented. If
260-
using an API in a manner currently undocumented achieves a particular useful
261-
result, a decision will need to be made whether or not that falls within the
262-
supported scope of that API; and if it does, it should be documented.
263-
264-
See [Breaking Changes to Internal Elements](#breaking-changes-to-internal-elements)
265-
on how to handle those types of changes.
220+
All functionality in the official Node.js documentation is part of the public
221+
API. Any undocumented object, property, method, argument, behavior, or event is
222+
internal. There are exceptions to this rule. Node.js users have come to rely on
223+
some undocumented behaviors. Collaborators treat many of those undocumented
224+
behaviors as public.
225+
226+
All undocumented functionality exposed via `process.binding(...)` is internal.
227+
228+
All undocumented functionality in `lib/internal/**/*.js` is internal. It is
229+
public, though, if it is re-exported by code in `lib/*.js`.
230+
231+
Non-exported `Symbol` properties and methods are internal.
232+
233+
Any undocumented object property or method that begins with `_` is internal.
234+
235+
Any native C/C++ APIs/ABIs requiring the `NODE_WANT_INTERNALS` flag are
236+
internal.
237+
238+
Sometimes, there is disagreement about whether functionality is internal or
239+
public. In those cases, the TSC makes a determination.
240+
241+
For undocumented APIs that are public, open a pull request documenting the API.
266242

267243
### Breaking Changes
268244

0 commit comments

Comments
 (0)