1# Contributing a new API to Node-API
2
3Node-API is the next-generation ABI-stable API for native addons.
4While improving the API surface is encouraged and welcomed, the following are
5a set of principles and guidelines to keep in mind while adding a new
6Node-API.
7
8* A new API **must** adhere to Node-API API shape and spirit.
9  * **Must** be a C API.
10  * **Must** not throw exceptions.
11  * **Must** return `napi_status`.
12  * **Should** consume `napi_env`.
13  * **Must** operate only on primitive data types, pointers to primitive
14    data types or opaque handles.
15  * **Must** be a necessary API and not a nice to have. Convenience APIs
16    belong in node-addon-api.
17  * **Must** not change the signature of an existing Node-API API or break
18    ABI compatibility with other versions of Node.js.
19* New API **should** be agnostic towards the underlying JavaScript VM.
20* New API PRs **must** have a corresponding documentation update.
21* New API PRs **must** be tagged as **node-api**.
22* There **must** be at least one test case showing how to use the API.
23* There **should** be at least one test case per interesting use of the API.
24* There **should** be a sample provided that operates in a realistic way
25  (operating how a real addon would be written).
26* A new API **should** be discussed at the Node-API team meeting.
27* A new API addition **must** be signed off by at least two members of
28  the Node-API team.
29* A new API addition **should** be simultaneously implemented in at least
30  one other VM implementation of Node.js.
31* A new API **must** be considered experimental for at least one minor
32  version release of Node.js before it can be considered for promotion out
33  of experimental.
34  * Experimental APIs **must** be documented as such.
35  * Experimental APIs **must** require an explicit compile-time flag
36    (`#define`) to be set to opt-in.
37  * A feature flag of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>` **must**
38    be added with each experimental feature in order to allow code to
39    distinguish between experimental features as present in one version of
40    Node.js versus another.
41  * Experimental APIs **must** be considered for backport.
42  * Experimental status exit criteria **must** involve at least the
43    following:
44    * A new PR **must** be opened in `nodejs/node` to remove experimental
45      status. This PR **must** be tagged as **node-api** and **semver-minor**.
46    * Exiting an API from experimental **must** be signed off by the team.
47    * If a backport is merited, an API **must** have a down-level
48      implementation.
49    * The API **should** be used by a published real-world module. Use of
50      the API by a real-world published module will contribute favorably
51      to the decision to take an API out of experimental status.
52    * The API **must** be implemented in a Node.js implementation with an
53      alternate VM.
54
55Since the adoption of the policy whereby moving to a later version of Node-API
56from an earlier version may entail rework of existing code, it is possible to
57introduce modifications to already-released Node-APIs, as long as the
58modifications affect neither the ABI nor the API of earlier versions. Such
59modifications **must** be accompanied by an opt-out flag. This provides add-on
60maintainers who take advantage of the initial compile-time flag to track
61impending changes to Node-API with
62
63* a quick fix to the breakage caused,
64* a notification that such breakage is impending, and thus
65* a buffer to adoption above and beyond the one provided by the initial
66  compile-time flag.
67