@@ -217,52 +217,28 @@ used in other CI test runs (such as `--worker`).
217
217
218
218
### Internal vs. Public API
219
219
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.
266
242
267
243
### Breaking Changes
268
244
0 commit comments