@@ -123,44 +123,39 @@ level of V8 within Node.js is updated or new patches are floated on V8.
123
123
124
124
Due to the nature of the JavaScript language, it can often be difficult to
125
125
establish a clear distinction between which parts of the Node.js implementation
126
- represent the "public" API Node.js users should assume to be stable and which
127
- are considered part of the "internal" implementation detail of Node.js itself.
128
- A general rule of thumb has been to base the determination off what
129
- functionality is actually * documented* in the official Node.js API
130
- documentation. However, it has been repeatedly demonstrated that either the
131
- documentation does not completely cover implemented behavior or that Node.js
132
- users have come to rely heavily on undocumented aspects of the Node.js
133
- implementation.
134
-
135
- While there are numerous exceptions, the following general rules should be
136
- followed to determine which aspects of the Node.js API are considered
137
- "internal":
138
-
139
- - Any and all functionality exposed via ` process.binding(...) ` is considered to
140
- be internal and * not* part of the Node.js Public API.
141
- - Any and all functionality implemented in ` lib/internal/**/*.js ` that is not
142
- re-exported by code in ` lib/*.js ` , or is not documented as part of the
143
- Node.js Public API, is considered to be internal.
144
- - Any object property or method whose key is a non-exported ` Symbol ` is
145
- considered to be an internal property.
146
- - Any object property or method whose key begins with the underscore ` _ ` prefix,
147
- and is not documented as part of the Node.js Public API, is considered to be
148
- an internal property.
126
+ represent the public API Node.js users should assume to be stable and which
127
+ are part of the internal implementation details of Node.js itself. A rule of
128
+ thumb is to base the determination off what functionality is actually
129
+ documented in the official Node.js API documentation. However, it has been
130
+ repeatedly demonstrated that either the documentation does not completely cover
131
+ implemented behavior or that Node.js users have come to rely heavily on
132
+ undocumented aspects of the Node.js implementation.
133
+
134
+ The following general rules should be followed to determine which aspects of the
135
+ Node.js API are internal:
136
+
137
+ - All functionality exposed via ` process.binding(...) ` is internal.
138
+ - All functionality implemented in ` lib/internal/**/*.js ` is internal unless it
139
+ is re-exported by code in ` lib/*.js ` or documented as part of the Node.js
140
+ Public API.
141
+ - Any object property or method whose key is a non-exported ` Symbol ` is an
142
+ internal property.
143
+ - Any object property or method whose key begins with the underscore ` _ ` prefix
144
+ is internal unless it is documented as part of the Node.js Public API.
149
145
- Any object, property, method, argument, behavior, or event not documented in
150
- the Node.js documentation is considered to be internal.
146
+ the Node.js documentation is internal.
151
147
- Any native C/C++ APIs/ABIs exported by the Node.js ` *.h ` header files that
152
- are hidden behind the ` NODE_WANT_INTERNALS ` flag are considered to be
153
- internal.
148
+ are hidden behind the ` NODE_WANT_INTERNALS ` flag are internal.
154
149
155
150
Exception to each of these points can be made if use or behavior of a given
156
151
internal API can be demonstrated to be sufficiently relied upon by the Node.js
157
152
ecosystem such that any changes would cause too much breakage. The threshold
158
- for what qualifies as " too much breakage" is to be decided on a case-by-case
153
+ for what qualifies as too much breakage is to be decided on a case-by-case
159
154
basis by the TSC.
160
155
161
156
If it is determined that a currently undocumented object, property, method,
162
157
argument, or event * should* be documented, then a pull request adding the
163
- documentation is required in order for it to be considered part of the " public"
158
+ documentation is required in order for it to be considered part of the public
164
159
API.
165
160
166
161
Making a determination about whether something * should* be documented can be
@@ -232,17 +227,12 @@ handling may have been made. Additional CI testing may be required.
232
227
233
228
#### When breaking changes actually break things
234
229
235
- Breaking changes are difficult primarily because they change the fundamental
236
- assumptions a user of Node.js has when writing their code and can cause
237
- existing code to stop functioning as expected -- costing developers and users
238
- time and energy to fix.
239
-
240
- Because breaking (semver-major) changes are permitted to land in master at any
241
- time, it should be * understood and expected* that at least some subset of the
242
- user ecosystem * may* be adversely affected * in the short term* when attempting
243
- to build and use Node.js directly from master. This potential instability is
244
- precisely why Node.js offers distinct Current and LTS release streams that
245
- offer explicit stability guarantees.
230
+ Because breaking (semver-major) changes are permitted to land on the master
231
+ branch at any time, at least some subset of the user ecosystem may be adversely
232
+ affected in the short term when attempting to build and use Node.js directly
233
+ from the master branch. This potential instability is why Node.js offers
234
+ distinct Current and LTS release streams that offer explicit stability
235
+ guarantees.
246
236
247
237
Specifically:
248
238
@@ -255,7 +245,7 @@ Specifically:
255
245
attempt to fix the issue will be made before the next release; If no fix is
256
246
provided then the commit will be reverted.
257
247
258
- When any change is landed in master, and it is determined that the such
248
+ When any changes are landed on the master branch and it is determined that the
259
249
changes * do* break existing code, a decision may be made to revert those
260
250
changes either temporarily or permanently. However, the decision to revert or
261
251
not can often be based on many complex factors that are not easily codified. It
@@ -297,18 +287,18 @@ recommended but not required.
297
287
298
288
### Deprecations
299
289
300
- Deprecation refers to the identification of Public APIs that should no longer
290
+ _ Deprecation _ refers to the identification of Public APIs that should no longer
301
291
be used and that may be removed or modified in non-backwards compatible ways in
302
- a future major release of Node.js. Deprecation * may* be used with internal APIs
303
- if there is expected impact on the user community.
292
+ a future major release of Node.js. Deprecation may be used with internal APIs if
293
+ there is expected impact on the user community.
304
294
305
- Node.js uses three fundamental Deprecation levels:
295
+ Node.js uses three Deprecation levels:
306
296
307
297
* * Documentation-Only Deprecation* refers to elements of the Public API that are
308
298
being staged for deprecation in a future Node.js major release. An explicit
309
299
notice indicating the deprecated status is added to the API documentation
310
- * but no functional changes are implemented in the code* . There will be no
311
- runtime deprecation warning emitted for such deprecations.
300
+ but no functional changes are implemented in the code. There will be no
301
+ runtime deprecation warnings emitted for such deprecations.
312
302
313
303
* * Runtime Deprecation* refers to the use of process warnings emitted at
314
304
runtime the first time that a deprecated API is used. A command-line
@@ -320,12 +310,11 @@ Node.js uses three fundamental Deprecation levels:
320
310
* * End-of-life* refers to APIs that have gone through Runtime Deprecation and
321
311
are ready to be removed from Node.js entirely.
322
312
323
- Documentation-Only Deprecations * may* be handled as semver-minor or
324
- semver-major changes. Such deprecations have no impact on the successful
325
- operation of running code and therefore should not be viewed as breaking
326
- changes.
313
+ Documentation-Only Deprecations may be handled as semver-minor or semver-major
314
+ changes. Such deprecations have no impact on the successful operation of running
315
+ code and therefore should not be viewed as breaking changes.
327
316
328
- Runtime Deprecations and End-of-life APIs (internal or public) * must* be
317
+ Runtime Deprecations and End-of-life APIs (internal or public) must be
329
318
handled as semver-major changes unless there is TSC consensus to land the
330
319
deprecation as a semver-minor.
331
320
@@ -338,7 +327,7 @@ the documentation for the assigned deprecation identifier must remain in the
338
327
Node.js API documentation.
339
328
340
329
<a id =" deprecation-cycle " ></a >
341
- A "Deprecation cycle" is one full Node.js major release during which an API
330
+ A _ Deprecation cycle _ is one full Node.js major release during which an API
342
331
has been in one of the three Deprecation levels. (Note that Documentation-Only
343
332
Deprecations may land in a Node.js minor release but must not be upgraded to
344
333
a Runtime Deprecation until the next major release.)
@@ -347,10 +336,10 @@ No API can be moved to End-of-life without first having gone through a
347
336
Runtime Deprecation cycle.
348
337
349
338
A best effort will be made to communicate pending deprecations and associated
350
- mitigations with the ecosystem as soon as possible (preferably * before* the pull
351
- request adding the deprecation lands in master). All deprecations included in
352
- a Node.js release should be listed prominently in the "Notable Changes" section
353
- of the release notes.
339
+ mitigations with the ecosystem as soon as possible (preferably before the pull
340
+ request adding the deprecation lands on the master branch ). All deprecations
341
+ included in a Node.js release should be listed prominently in the "Notable
342
+ Changes" section of the release notes.
354
343
355
344
### Involving the TSC
356
345
@@ -375,8 +364,8 @@ The TSC should serve as the final arbiter where required.
375
364
* The rebase method changes the author.
376
365
* The squash & merge method has been known to add metadata to the
377
366
commit title.
378
- * If more than one author has contributed to the PR, only the
379
- latest author will be considered during the squashing.
367
+ * If more than one author has contributed to the PR, keep the most recent
368
+ author when squashing.
380
369
381
370
Always modify the original commit message to include additional meta
382
371
information regarding the change process:
@@ -628,10 +617,10 @@ TSC for further discussion.
628
617
#### How are LTS Branches Managed?
629
618
630
619
There are currently two LTS branches: ` v6.x ` and ` v4.x ` . Each of these is paired
631
- with a " staging" branch: ` v6.x-staging ` and ` v4.x-staging ` .
620
+ with a staging branch: ` v6.x-staging ` and ` v4.x-staging ` .
632
621
633
- As commits land in ` master ` , they are cherry-picked back to each staging
634
- branch as appropriate. If the commit applies only to the LTS branch, the
622
+ As commits land on the master branch , they are cherry-picked back to each
623
+ staging branch as appropriate. If the commit applies only to the LTS branch, the
635
624
PR must be opened against the * staging* branch. Commits are selectively
636
625
pulled from the staging branch into the LTS branch only when a release is
637
626
being prepared and may be pulled into the LTS branch in a different order
0 commit comments