From c7a2a42da45e87345b6e4f863ea6ba7f4effd135 Mon Sep 17 00:00:00 2001 From: Arunesh Chandra Date: Tue, 23 May 2017 08:20:34 -0700 Subject: [PATCH 1/4] doc: How to publish N-API package --- .../en/docs/guides/publishing-napi-modules.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 locale/en/docs/guides/publishing-napi-modules.md diff --git a/locale/en/docs/guides/publishing-napi-modules.md b/locale/en/docs/guides/publishing-napi-modules.md new file mode 100644 index 0000000000000..633063f21bf10 --- /dev/null +++ b/locale/en/docs/guides/publishing-napi-modules.md @@ -0,0 +1,47 @@ +## To publish N-API version of a package alongside a 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 `package.json`. For `iotivity-node`, the version + becomes `1.2.0-2`. + - Go through the release checklist (ensure tests/demos/docs are OK) + - `npm publish` + - Then, publish the N-API version: + - Update the version in `package.json`. For `iotivity-node`, the version + becomes `1.2.0-3`. For version number, the field after the dash (-) allows + quite a bit of flexibility to insert any text. e.g. `1.2.0-napi`. + - Go through the release checklist (ensure tests/demos/docs are OK) + - `npm publish --tag n-api` + +In this example, tagging the release with `n-api` has ensured 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`. This will install the non-N-API version +by default. The user will 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 + +To add the N-API version of `iotivity-node` as a dependency, the `package.json` +will look like this: + +```JSON + "dependencies": { + "iotivity-node": "n-api" + } +``` + +Note that, unlike regular versions, tagged versions cannot be addressed by +version ranges such as `"^2.0.0"` inside `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 the package using the same tag, `npm update` +will receive the later version. This should be acceptable given the currently +experimental nature of N-API. To depend on an N-API-enabled version other than +the latest published, the `package.json` dependency will have to refer to the +exact version like the following: + +```JSON + "dependencies": { + "iotivity-node": "1.2.0-3" + } +``` From 2f1e1c5bb0ef4c9e4ee1037e55fe55a65b9ce1b1 Mon Sep 17 00:00:00 2001 From: Arunesh Chandra Date: Tue, 23 May 2017 09:33:29 -0700 Subject: [PATCH 2/4] Added link to using npm with tags --- locale/en/docs/guides/publishing-napi-modules.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/locale/en/docs/guides/publishing-napi-modules.md b/locale/en/docs/guides/publishing-napi-modules.md index 633063f21bf10..af92ab818a5d8 100644 --- a/locale/en/docs/guides/publishing-napi-modules.md +++ b/locale/en/docs/guides/publishing-napi-modules.md @@ -18,7 +18,8 @@ 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`. This will install the non-N-API version by default. The user will have to run `npm install iotivity-node@n-api` to -receive the N-API version. +receive the N-API version. For more information on usig tags with npm check +out https://docs.npmjs.com/getting-started/using-tags ## To introduce a dependency on an N-API version of a package From 9330f6ff39087ac8d1da4aaf01debebc9b187f5f Mon Sep 17 00:00:00 2001 From: Arunesh Chandra Date: Tue, 23 May 2017 09:36:44 -0700 Subject: [PATCH 3/4] Fixed typo --- locale/en/docs/guides/publishing-napi-modules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/locale/en/docs/guides/publishing-napi-modules.md b/locale/en/docs/guides/publishing-napi-modules.md index af92ab818a5d8..6e9032d0656ca 100644 --- a/locale/en/docs/guides/publishing-napi-modules.md +++ b/locale/en/docs/guides/publishing-napi-modules.md @@ -18,7 +18,7 @@ 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`. This will install the non-N-API version by default. The user will have to run `npm install iotivity-node@n-api` to -receive the N-API version. For more information on usig tags with npm check +receive the N-API version. For more information on using tags with npm check out https://docs.npmjs.com/getting-started/using-tags ## To introduce a dependency on an N-API version of a package From a9f9b84876d7ae0af323017ead7103cbd936a9b9 Mon Sep 17 00:00:00 2001 From: Arunesh Chandra Date: Thu, 25 May 2017 09:29:00 -0700 Subject: [PATCH 4/4] Updating with PR feedback --- .../en/docs/guides/publishing-napi-modules.md | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/locale/en/docs/guides/publishing-napi-modules.md b/locale/en/docs/guides/publishing-napi-modules.md index 6e9032d0656ca..0014535c723e8 100644 --- a/locale/en/docs/guides/publishing-napi-modules.md +++ b/locale/en/docs/guides/publishing-napi-modules.md @@ -7,9 +7,10 @@ The following steps are illustrated using the package `iotivity-node`: - Go through the release checklist (ensure tests/demos/docs are OK) - `npm publish` - Then, publish the N-API version: - - Update the version in `package.json`. For `iotivity-node`, the version - becomes `1.2.0-3`. For version number, the field after the dash (-) allows - quite a bit of flexibility to insert any text. e.g. `1.2.0-napi`. + - Update the version in `package.json`. In the case of `iotivity-node`, + the version becomes `1.2.0-3`. For versioning, we recommend following + the pre-release version scheme as described by + [semver.org](http://semver.org/#spec-item-9) e.g. `1.2.0-napi`. - Go through the release checklist (ensure tests/demos/docs are OK) - `npm publish --tag n-api` @@ -19,7 +20,7 @@ will not be installed if someone chooses to install `iotivity-node` by simply running `npm install iotivity-node`. This will install the non-N-API version by default. The user will have to run `npm install iotivity-node@n-api` to receive the N-API version. For more information on using tags with npm check -out https://docs.npmjs.com/getting-started/using-tags +out ["Using dist-tags"][]. ## To introduce a dependency on an N-API version of a package @@ -32,17 +33,21 @@ will look like this: } ``` -Note that, unlike regular versions, tagged versions cannot be addressed by -version ranges such as `"^2.0.0"` inside `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 the package using the same tag, `npm update` -will receive the later version. This should be acceptable given the currently -experimental nature of N-API. To depend on an N-API-enabled version other than -the latest published, the `package.json` dependency will have to refer to the -exact version like the following: +**Note:** As explained in +["Using dist-tags"][], unlike regular versions, tagged versions cannot be +addressed by version ranges such as `"^2.0.0"` inside `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 the package using the +same tag, `npm update` will receive the later version. This should be acceptable +given the currently experimental nature of N-API. To depend on an N-API-enabled +version other than the latest published, the `package.json` dependency will +have to refer to the exact version like the following: ```JSON "dependencies": { "iotivity-node": "1.2.0-3" } ``` + + +["Using dist-tags"]: https://docs.npmjs.com/getting-started/using-tags