Commit a6c748f
doc: experimental flag for global accessible APIs
Explicitly document that adding an API to the global scope requires
`semver-major` label. Waiving the `semver-major` requires a regular
TSC consensus process.
PR-URL: #54330
Refs: #54329
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>1 parent 54af473 commit a6c748f
1 file changed
Lines changed: 17 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -437,6 +437,23 @@ For pull requests introducing new core modules: | |||
| 437 | 437 | * Land with a [Stability Index][] of Experimental. The module must remain | |
| 438 | 438 | Experimental until a semver-major release. | |
| 439 | 439 | ||
| 440 | + ### Introducing new APIs on the global scope | ||
| 441 | + | ||
| 442 | + Exposing new APIs to the global scope that are available without | ||
| 443 | + an `import` or `require` call, including introducing new interfaces on | ||
| 444 | + `globalThis` like `globalThis.navigator`, and adding new properties on | ||
| 445 | + interfaces on `globalThis` like well known symbols, could break feature | ||
| 446 | + detection and Node.js environment detection. | ||
| 447 | + | ||
| 448 | + Exposing new APIs to the global scope unconditionally without any CLI | ||
| 449 | + flags must always be labeled as `semver-major`. The `semver-major` label may | ||
| 450 | + be waived through the regular TSC consensus process. | ||
| 451 | + | ||
| 452 | + It is recommended to start with exposing APIs to the global scope with an | ||
| 453 | + experimental CLI flag `--experimental-<feature-name>`, without being labeled as | ||
| 454 | + `semver-major`. When the new APIs are feature complete, turn the flag on by | ||
| 455 | + default with a CLI flag `--no-experimental-<feature-name>` to opt-out. | ||
| 456 | + | ||
| 440 | 457 | ### Additions to Node-API | |
| 441 | 458 | ||
| 442 | 459 | Node-API provides an ABI-stable API guaranteed for future Node.js versions. | |
0 commit comments