GeezerVison is showing github.com — doc: experimental flag for global accessible APIs · nodejs/node@a6c748f
File tree
Expand file treeCollapse file tree
Open diff view settings
Expand file treeCollapse file tree
Open diff view settings
Collapse file
Copy file name to clipboardExpand all lines: doc/contributing/collaborator-guide.md +17Lines changed: 17 additions & 0 deletions - Display the source diff
- Display the rich diff
| 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. |
|