What is the actual version of this?

[BillyONeal]

In microsoft/vcpkg#29743 we are confused as to what version we should use when listing the contents of this repo.

Let's take an example:

• Release: 0.0.5
• Node API version: 8
• From upstream: 19.8.1

See also: nodejs/node#46641 (comment)

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]

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 nodejs/node@62cde61 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]

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]

So, according to option 1, I'm using v0.0.5 for microsoft/vcpkg#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]

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

[NickNaso]

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