search

nodejs / node-api-headers

Repository used to make the N-API headers more accessible
MIT License
32 stars 13 forks source link

What is the actual version of this? #25

Closed BillyONeal closed 1 year ago

BillyONeal commented 1 year ago

In https://github.com/microsoft/vcpkg/pull/29743 we are confused as to what version we should use when listing the contents of this repo.

Let's take an example:

See also: https://github.com/nodejs/node/pull/46641#issuecomment-1430091795

NodeJS folks there seem to be suggesting "8" but if it would ever be distinguishable to a user for any reason to use a different upstream tag, that means the upstream tag needs to be in the version somehow...

legendecas commented 1 year ago

Node-api C headers are always expected to be compatible when NAPI_VERSION is set to a valid node-api version number. Its version (i.e. 8) is released separately from the Node.js version stream (i.e. 19.8.1) and changes are backported to active Node.js LTS lines (e.g. 16.x and 18.x).

So this package always publishes with the latest node-api c headers. The package also contains a set of JS APIs to get node-api symbols.

@nodejs/node-api I think the options for us would be:

  1. Publish v1.0.0 of this package to indicate this package is stable to be depended on, and publishes minor versions when there are any updates on the headers since the headers are always compatible. If there is any breaking change in the JS APIs to get the node-api symbols, we can publish a major version of the package.
  2. Publish v8.0.0 to align with the node-api version. However, updates like https://github.com/nodejs/node/commit/62cde6195f13369606f9301dd27260e517b88115 that are not bound to a specific node-api version would only be released in the latest version of the headers package.

I'm personally leaning towards option 1 and adding a note in the package README to explain the versioning rationale.

NickNaso commented 1 year ago

Hi everybody, I worked on this package from the beginning and I always thought to adopt the option 1 proposed by @legendecas. I prefer this option because the package has its own JS api and assets (es. definition files for windows import lib) that could change in the future and I think that keeping the two versions Node-API version and the node-api-headers version separate can guarantee us greater flexibility.

Pospelove commented 1 year ago

So, according to option 1, I'm using v0.0.5 for https://github.com/microsoft/vcpkg/pull/29743 then.

It won't be an issue to update to v1.0.0 once it gets published.

Thank you for your detailed answers :)

BillyONeal commented 1 year ago

Thanks, I think we have a reasonable path forward now!

NickNaso commented 1 year ago

I'd like to discuss about this in today meeting.