fbc52e5729The term "native module" dates back to some of the oldest code in the code base. Within the context of Node.js core it usually refers to modules that are native to Node.js (e.g. fs, http), but it can cause confusion for people who don't work on this part of the code base, as "native module" can also refer to native addons - which is even the case in some of the API docs and error messages. This patch tries to make the usage of these terms more consistent. Now within the context of Node.js core: - JavaScript scripts that are built-in to Node.js are now referred to as "built-in(s)". If they are available as modules, they can also be referred to as "built-in module(s)". - Dynamically-linked shared objects that are loaded into the Node.js processes are referred to as "addons". We will try to avoid using the term "native modules" because it could be ambiguous. Changes in this patch: File names: - node_native_module.h -> node_builtins.h, - node_native_module.cc -> node_builtins.cc C++ binding names: - `native_module` -> `builtins` `node::Environment`: - `native_modules_without_cache` -> `builtins_without_cache` - `native_modules_with_cache` -> `builtins_with_cache` - `native_modules_in_snapshot` -> `builtins_in_cache` - `native_module_require` -> `builtin_module_require` `node::EnvSerializeInfo`: - `native_modules` -> `builtins `node::native_module::NativeModuleLoader`: - `native_module` namespace -> `builtins` namespace - `NativeModuleLoader` -> `BuiltinLoader` - `NativeModuleRecordMap` -> `BuiltinSourceMap` - `NativeModuleCacheMap` -> `BuiltinCodeCacheMap` - `ModuleIds` -> `BuiltinIds` - `ModuleCategories` -> `BuiltinCategories` - `LoadBuiltinModuleSource` -> `LoadBuiltinSource` `loader.js`: - `NativeModule` -> `BuiltinModule` (the `NativeModule` name used in `process.moduleLoadList` is kept for compatibility) And other clarifications in the documentation and comments. PR-URL: https://github.com/nodejs/node/pull/44135 Backport-PR-URL: https://github.com/nodejs/node/pull/45663 Fixes: https://github.com/nodejs/node/issues/44036 Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Jan Krems <jan.krems@gmail.com>
49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# 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.
|
|
|
|
* 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.
|
|
* 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.
|