Investigate using @n-api npm tag

[gabrielschulhof]

What is the maintainers' workflow for publishing?

What is the workflow for depending on vs. depending on the mainstream V8 version? (package.json)

[aruneshchandra]

It will be also useful to understand what might be the workflow of older Node.js versions which will get N-API later on.

[jasongin]

npm tags documentation

And don't confuse tags with npm scopes, which also use a @ prefix but are something entirely different.

[gabrielschulhof]

@jasongin I tried to build iotivity-node against node-api and I found that the headers are a bit behind - for example, napi_get_last_error_info() doesn't have the env parameter. I kinda need that before I can publish. Is that coming soon?

[jasongin]

@gabrielschulhof The node-api repo was updated for that change last week. Make sure you have the latest. If there are any remaining issues, please open issues under that repo.

[gabrielschulhof]

@jasongin I think you may have grabbed an older version of the header/source code when you added support for pre-N-API Node.js: https://github.com/nodejs/node-api/blob/master/src/node_api.h#L97

[gabrielschulhof]

I'm trying to build on Node.js version 4.0.0 BTW.

[jasongin]

Oh, yes that copy of the code hasn't been updated in a while. I was waiting for things to settle before I updated it again. You can manually copy the node_api* source files from the nodejs/node master branch; there aren't supposed to be any differences.

[gabrielschulhof]

I know, but I want to eventually publish to npm.

[gabrielschulhof]

But OK, I'll make a fork and depend on that for now.

…

On Fri, Apr 14, 2017 at 10:51 PM, Schulhof, Gabriel ***@***.***> wrote: I know, but I want to eventually publish to npm.

[gabrielschulhof]

I have just published iotivity-node version 1.2.0-3 to the "n-api" tag. When you type npm install iotivity-node, you get 1.2.0-2, which is the latest published version. However, if you type npm install iotivity-node@n-api, you get 1.2.0-3.

So, I think the way tags work is like this:

latest	n-api
...	...
1.2.1-1?
	1.2.1-0?
↓past	↑future
	1.2.0-3
1.2.0-2
1.2.0-1
1.2.0-0
...	...

So, in terms of semver, I think packages can take advantage of the dash-field. npm accepts it just fine. So, for example, version on the latest tag can take the traditional form of major.minor.patch, whereas packages on the n-api tag can take the same form, except with a -0 attached.

[gabrielschulhof]

I guess in terms of developers' workflow, how they maintain their bindings (branch/prepublish script/etc.) is up to them, but basically, to publish is as simple as

npm login
npm publish

for V8, and

npm login
npm publish --tag n-api

for N-API.

[gabrielschulhof]

It looks like only one version can be tagged in a certain way. This means that when a later version is tagged as either @latest or @n-api the versions before it are all folded into a single sequence of versions. So, npm tags are not like git branches. There is only one branch with tags along the way which each tag moving forward as a new version is published under that tag. Below is the npm view output of a dummy package I published.

{ name: 'npm-test-p4ck4g3',
  'dist-tags': { latest: '1.0.1', sometag: '1.0.1-sometag' },
  versions: [ '1.0.0-sometag', '1.0.0', '1.0.1-sometag', '1.0.1' ],
  maintainers: [ 'gabrielschulhof <[email protected]>' ],
  time: 
   { modified: '2017-04-27T19:25:28.770Z',
     created: '2017-04-27T19:23:29.321Z',
     '1.0.0': '2017-04-27T19:23:29.321Z',
     '1.0.0-sometag': '2017-04-27T19:24:52.541Z',
     '1.0.1': '2017-04-27T19:25:11.315Z',
     '1.0.1-sometag': '2017-04-27T19:25:28.770Z' },
  license: 'ISC',
  readmeFilename: '',
  version: '1.0.1',
  description: '',
  main: 'index.js',
  scripts: { test: 'echo "Error: no test specified" && exit 1' },
  author: '',
  dist: 
   { shasum: 'a61f936d507bafd1ae5608c95625bd74a7cf06a0',
     tarball: 'https://registry.npmjs.org/npm-test-p4ck4g3/-/npm-test-p4ck4g3-1.0.1.tgz' },
  directories: {} }

[gabrielschulhof]

Dependents can write

  ...
  "dependencies": {
    "npm-test-p4ck4g3": "sometag"
  }
  ...

and they will receive the latest version published under the tag sometag, however, they can specify no version ranges such that only those that were once tagged sometag will be examined.

[gabrielschulhof]

We should ask ourselves: are we going to be experimental for so long that dependents of modules will want to refer to a range of N-API-enabled versions? Being able to tag a single version as N-API-enabled and then moving that forward should be enough to get us through the experimental period.

[jasongin]

Even if N-API is not experimental for more than a few months, package authors may consider their N-API port to be experimental for far longer, if they feel they need more time to stabilize after a port that touched a lot of code in a complex package.

[gabrielschulhof]

That's fair. Still, would those depending on such a module ever need to refer to a range of past tagged versions, given that all such versions are experimental? And let's remember that all we're losing is the (in?)convenience of receiving the latest package that matches your specified range. Your choice is instead limited to either the latest (if you put "n-api" as your desired version) or a specific version which is known to be N-API-enabled (if you put that specific version as your desired version).

[gabrielschulhof]

I say (in?) because receiving a newer version is sometimes undesirable because it introduces churn. That's what shrinkwrap is all about. However, when you're in experimental territory anyway, I would argue that the more tools you have to keep the parts from moving, the better. So, perhaps the inability to specify carets or tildes is actually quite desirable.

[aruneshchandra]

Command line experience
npm install npm-test-p4ck4g3@sometag

[gabrielschulhof]

To publish an N-API version of your package alongside your non-N-API version

The following steps are illustrated using the package iotivity-node:

• First, publish the non-N-API version:
  • Update the version in your package.json. For iotivity-node, the version becomes 1.2.0-2.
  • Go through your release checklist (make sure tests, demos, and docs are OK)
  • npm publish
• Then, publish the N-API version:
  • Update the version in your package.json. For iotivity-node, the version becomes 1.2.0-3. You may place something else after the dash (-) in the version number, because that field allows quite a bit of freedom. For example, you could say 1.2.0-napi.
  • Go through your release checklist (make sure tests, demos, and docs are OK)
  • npm publish --tag n-api

Tagging the release with n-api has ensured for iotivity-node that, although version 1.2.0-3 is later than the non-N-API published version (1.2.0-2), it will not be installed if someone chooses to install iotivity-node by simply running npm install iotivity-node. Thus, the non-N-API version will be installed by default. The user would have to run npm install iotivity-node@n-api to receive the N-API version.

To introduce a dependency on an N-API version of a package

For example, to add the N-API version of iotivity-node to your package's dependencies, simply run npm install --save iotivity-node@n-api. Thus, you will receive version 1.2.0-3, which is the latest N-API-enabled version of iotivity-node. The dependency in your package.json will look like this:

  "dependencies": {
    "iotivity-node": "n-api"
  }

Note that, unlike regular versions, tagged versions cannot be addressed by version ranges such as "^2.0.0" in your package.json. The reason for this is that the tag refers to exactly one version. So, if the package maintainer chooses to tag a later version of their package using the same tag, you will receive the later version when you run npm update. This should be acceptable given the currently experimental nature of N-API. If you wish to depend on an N-API-enabled version other than the latest published, you must change your package.json dependency to refer to the exact version on which you wish to depend:

  "dependencies": {
    "iotivity-node": "1.2.0-3"
  }