doc, meta: organize contributing to Node-API guide

doc/contributing/adding-new-napi-api.md

@@ -1,66 +1,60 @@
 # Contributing a new API to Node-API
 
-Node-API is the next-generation ABI-stable API for native addons.
-While improving the API surface is encouraged and welcomed, the following are
-a set of principles and guidelines to keep in mind while adding a new
-Node-API.
+Node-API is the ABI-stable API for native addons. We encourage contributions to enhance the API,
+but also ensuring compatibility and adherence to guidelines. When adding a new API to Node-API,
+please follow these principles and guidelines:
 
-* A new API **must** adhere to Node-API API shape and spirit.
-  * **Must** be a C API.
-  * **Must** not throw exceptions.
-  * **Must** return `napi_status`.
-  * **Should** consume `napi_env`.
-  * **Must** operate only on primitive data types, pointers to primitive
-    data types or opaque handles.
-  * **Must** be a necessary API and not a nice to have. Convenience APIs
-    belong in node-addon-api.
-  * **Must** not change the signature of an existing Node-API API or break
-    ABI compatibility with other versions of Node.js.
-* New API **should** be agnostic towards the underlying JavaScript VM.
-* New API PRs **must** have a corresponding documentation update.
-* New API PRs **must** be tagged as **node-api**.
-* There **must** be at least one test case showing how to use the API.
-* There **should** be at least one test case per interesting use of the API.
-* There **should** be a sample provided that operates in a realistic way
-  (operating how a real addon would be written).
-* A new API **should** be discussed at the Node-API team meeting.
-* A new API addition **must** be signed off by at least two members of
-  the Node-API team.
-* A new API addition **should** be simultaneously implemented in at least
-  one other VM implementation of Node.js.
-* A new API **must** be considered experimental for at least one minor
-  version release of Node.js before it can be considered for promotion out
-  of experimental.
-  * Experimental APIs **must** be documented as such.
-  * Experimental APIs **must** require an explicit compile-time flag
-    (`#define`) to be set to opt-in.
-  * A feature flag of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>` **must**
-    be added with each experimental feature in order to allow code to
-    distinguish between experimental features as present in one version of
-    Node.js versus another.
-  * Experimental APIs **must** be considered for backport.
-  * Experimental status exit criteria **must** involve at least the
-    following:
-    * A new PR **must** be opened in `nodejs/node` to remove experimental
-      status. This PR **must** be tagged as **node-api** and **semver-minor**.
-    * Exiting an API from experimental **must** be signed off by the team.
-    * If a backport is merited, an API **must** have a down-level
-      implementation.
-    * The API **should** be used by a published real-world module. Use of
-      the API by a real-world published module will contribute favorably
-      to the decision to take an API out of experimental status.
-    * The API **must** be implemented in a Node.js implementation with an
-      alternate VM.
+## Core principles
 
-Since the adoption of the policy whereby moving to a later version of Node-API
-from an earlier version may entail rework of existing code, it is possible to
-introduce modifications to already-released Node-APIs, as long as the
-modifications affect neither the ABI nor the API of earlier versions. Such
-modifications **must** be accompanied by an opt-out flag. This provides add-on
-maintainers who take advantage of the initial compile-time flag to track
-impending changes to Node-API with
+1. **Adherence to Node-API standards**
+   * **Must** be a C API.
+   * **Must** not throw exceptions.
+   * **Must** return `napi_status`.
+   * **Should** consume `napi_env`.
+   * **Must** operate on primitive data types, pointers to primitive data types, or opaque handles.
+   * **Must** be a necessary API, not a convenience API (which belongs in node-addon-api).
+   * **Must** not alter the signature of existing Node-API or break ABI compatibility with other Node.js versions.
 
-* a quick fix to the breakage caused,
-* a notification that such breakage is impending, and thus
-* a buffer to adoption above and beyond the one provided by the initial
-  compile-time flag.
+2. **Maintaining VM agnosticism**
+   * New APIs **should** be compatible with various JavaScript VMs.
+
+## Documentation and testing
+
+1. **Documentation**
+   * PRs introducing new APIs **must** include corresponding documentation updates.
+   * Experimental APIs **must** be clearly documented as experimental and require an explicit compile-time flag
+     to opt-in (`#define`).
+
+2. **Testing**
+   * PRs **must** include at least one test case demonstrating API usage.
+   * **Should** include test cases for various interesting uses of the API.
+   * **Should** provide a sample demonstrating realistic usage, similar to a real-world addon.
+
+## Process and approval
+
+1. **Team discussion**
+   * New APIs **should** be discussed in a Node-API team meeting.
+
+2. **Review and approval**
+   * A new API addition **must** be signed off by at least two Node-API team members.
+   * **Should** be implemented in at least one other VM implementation of Node.js.
+
+3. **Experimental phase**
+   * New APIs **must** be marked as experimental for at least one minor Node.js release before promotion.
+   * **Must** have a feature flag (`NODE_API_EXPERIMENTAL_HAS_<FEATURE>`) for distinguishing experimental features.
+   * **Must** be considered for backporting.
+   * Exit criteria from experimental status include:
+     * Opening a PR in `nodejs/node` to remove experimental status, tagged as **node-api** and **semver-minor**.
+     * Approval by the Node-API team.
+     * Availability of a down-level implementation if backporting is needed.
+     * Usage by a published real-world module to support de-experimentation.
+     * Implementation in a Node.js version with an alternate VM.
+
+## Modifying released APIs
+
+Changes to existing APIs that do not affect ABI or API compatibility with earlier versions are permissible
+with an opt-out flag. This helps addon maintainers by providing:
+
+* Quick fixes for breakages.
+* Notifications of impending changes.
+* An additional buffer for adoption beyond the initial compile-time flag.