From b83e9b375ca945210211a65eb79f368bb016e2ba Mon Sep 17 00:00:00 2001 From: Chengzhong Wu Date: Mon, 12 Aug 2024 11:44:46 +0100 Subject: [PATCH] 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. --- doc/contributing/collaborator-guide.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/contributing/collaborator-guide.md b/doc/contributing/collaborator-guide.md index a7021db9b2af48..884f58a8e2774e 100644 --- a/doc/contributing/collaborator-guide.md +++ b/doc/contributing/collaborator-guide.md @@ -437,6 +437,16 @@ For pull requests introducing new core modules: * Land with a [Stability Index][] of Experimental. The module must remain Experimental until a semver-major release. +### Introducing new APIs on the global scope + +Exposing APIs to the global scope unconditionally without any CLI flags must +always be labeled as `semver-major`. The `semver-major` label may be waived +through the regular TSC consensus process. + +It is recommended to start with exposing APIs to the global scope with an +experimental flag, without being labeled as `semver-major`. When the API is a +release candidate, turn the flag on by default with a CLI flag to opt-out. + ### Additions to Node-API Node-API provides an ABI-stable API guaranteed for future Node.js versions.