From 50dca30b1a9e1f0f46651de0dc379bdf2bc64421 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/api/documentation.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/api/documentation.md b/doc/api/documentation.md index edac7426fe0324..e5dd5989a26bee 100644 --- a/doc/api/documentation.md +++ b/doc/api/documentation.md @@ -66,6 +66,16 @@ used. Bugs or behavior changes may surprise users when Experimental API modifications occur. To avoid surprises, use of an Experimental feature may need a command-line flag. Experimental features may also emit a [warning][]. +### 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. + ## Stability overview