The following are a set of proposed principles to add an API to the N-API surface. Text in italics are my comments/annotations. Feedback/thoughts welcome- I'm throwing this out there to start the discussion. Thanks to @kfarnung for his early feedback.

N-API design principles

A new API must adhere to N-API API shape and spirit (spirit is kind of what @mhdawson talks about here)
- 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 datatypes 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 N-API API or break ABI compatibility with other versions of Node.
New API should be agnostic towards the underlying JavaScript VM
New API request PRs must have a corresponding documentation update
New API request PRs must be tagged as n-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 N-API working group meeting
A new API addition must be signed off by at least two members of the N-API WG
A new API addition should be simultaneously implemented in at least one other VM implementation of Node.
A new API must be considered experimental for at least one minor version release of Node 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 n-api and semver-minor.
  - Exiting an API from experimental must be signed off by the working group.
  - 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 implementation with an alternate VM (Node-ChakraCore can provide SLAs here e.g we’ll review PRs within a week, attempt best effort to implement within a week or sign off within that time)

Uh oh!

Document guidance on adding APIs to N-API #301

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions