1# Contributing a new API to Node-API 2 3Node-API is the next-generation ABI-stable API for native modules. 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 **n-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 * Experimental APIs **must** be considered for backport. 38 * Experimental status exit criteria **must** involve at least the 39 following: 40 * A new PR **must** be opened in `nodejs/node` to remove experimental 41 status. This PR **must** be tagged as **n-api** and **semver-minor**. 42 * Exiting an API from experimental **must** be signed off by the team. 43 * If a backport is merited, an API **must** have a down-level 44 implementation. 45 * The API **should** be used by a published real-world module. Use of 46 the API by a real-world published module will contribute favorably 47 to the decision to take an API out of experimental status. 48 * The API **must** be implemented in a Node.js implementation with an 49 alternate VM. 50