@jsdevtools/npm-publish 2.2.2 → 3.0.0

package/README.md

@@ -6,23 +6,29 @@
 [![License](https://img.shields.io/npm/l/@jsdevtools/npm-publish.svg)](LICENSE)
 [![Buy us a tree](https://img.shields.io/badge/Treeware-%F0%9F%8C%B3-lightgreen)](https://plant.treeware.earth/JS-DevTools/npm-publish)
 
-Publish your packages to npm automatically in GitHub Actions by updating the version number.
+Publish packages to npm automatically in GitHub Actions by updating the version number.
+
+- [Change log][releases]
+- [v2 to v3 migration guide](#v2-to-v3)
+- [v1 to v3 migration guide](#v1-to-v3)
+
+[releases]: https://github.com/JS-DevTools/npm-publis/releases
 
 ## Features
 
-- 🧠 **Smart**<br>
+- 🧠 **Smart**
   Only publishes if the version number in `package.json` differs from the latest on npm.
 
-- 🛠 **Configurable**<br>
+- 🛠 **Configurable**
   Customize the version-checking behavior, the registry URL, and path of your package.
 
-- 🔐 **Secure**<br>
-  Keeps your npm authentication token secret. Doesn't read from or write to `~/.npmrc`.
+- 🔐 **Secure**
+  Keeps your npm authentication token secret. Doesn't read nor write to `~/.npmrc`.
 
-- ⚡ **Fast**<br>
+- ⚡ **Fast**
   100% JavaScript (which is faster than Docker) and bundled to optimize loading time.
 
-- 📤 **Outputs**<br>
+- 📤 **Outputs**
   Exposes the old and new version numbers, and the type of change (major, minor, patch, etc.) as variables that you can use in your workflow.
 
 ## Usage
@@ -35,78 +41,6 @@ This package can be used three different ways:
 
 - 🖥 A [**CLI**](#command-line-interface) that you run in your terminal
 
-## v2 Migration Guide
-
-The v1 to v2 upgrade brought a few notable **breaking changes**. To migrate, make the following updates:
-
-- The `type` output is now an empty string instead of `'none'` when no release occurs
-  ```diff
-    - run: echo "Version changed!"
-  -   if: ${{ steps.publish.outputs.type != 'none' }}
-  +   if: ${{ steps.publish.outputs.type }}
-  ```
-- The `--ignore-scripts` option is now passed to `npm publish` as a security precaution. If you define any publish lifecycle scripts - `prepublishOnly`, `prepack`, `prepare`, `postpack`, `publish`, `postpublish` - run them explicitly or set the `ignore-scripts` input to `false`.
-  ```diff
-    with:
-      token: ${{ secrets.NPM_TOKEN }}
-  +   ignore-scripts: false
-  ```
-- The workflow's `.npmrc` file is no longer modified. If you have any workarounds to adjust for this misbehavior - for example, if you're using `actions/setup-node` to configure `.npmrc` - you should remove them.
-
-  ```diff
-    - uses: actions/setup-node@v3
-      with:
-        node-version: '18'
-        registry-url: https://registry.npmjs.org/
-
-    - uses: JS-DevTools/npm-publish@v1
-      with:
-        token: ${{ secrets.NPM_TOKEN }}
-
-    - name: Do some more stuff with npm
-      run: npm whoami
-      env:
-  -     INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}
-  +     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-  ```
-
-- The `check-version` and `greater-version-only` options have been removed and replaced with `strategy`.
-  - Use `strategy: all` (default) to publish all versions that do not yet exist in the registry.
-    ```diff
-      with:
-        token: ${{ secrets.NPM_TOKEN }}
-    -   check-version: true
-    -   greater-version-only: false
-    +   strategy: all
-    ```
-  - Use `strategy: upgrade` to only publish versions that upgrade the selected tag.
-    ```diff
-      with:
-        token: ${{ secrets.NPM_TOKEN }}
-    -   check-version: true
-    -   greater-version-only: true
-    +   strategy: upgrade
-    ```
-  - `check-version: false` has been removed. You may not need this action if you're not checking already published versions; [you can `npm` directly][publishing-nodejs-packages], instead.
-    ```diff
-    - - uses: JS-DevTools/npm-publish@v1
-    -   with:
-    -     token: ${{ secrets.NPM_TOKEN }}
-    -     check-version: false
-    + - uses: actions/setup-node@v3
-    +   with:
-    +     node-version: '18'
-    +     registry-url: https://registry.npmjs.org/
-    + - run: npm publish
-    +   env:
-    +     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-    ```
-
-See the [change log][] for more details and other changes in the v2 release.
-
-[publishing-nodejs-packages]: https://docs.github.com/actions/publishing-packages/publishing-nodejs-packages
-[change log]: https://github.com/JS-DevTools/npm-publish/releases
-
 ## GitHub Action
 
 To use the GitHub Action, you'll need to add it as a step in your [workflow file][]. By default, the only thing you need to do is set the `token` parameter to your [npm authentication token][].
@@ -120,13 +54,13 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: "18"
+          node-version: "20"
       - run: npm ci
       - run: npm test
-      - uses: JS-DevTools/npm-publish@v2
+      - uses: JS-DevTools/npm-publish@v3
         with:
           token: ${{ secrets.NPM_TOKEN }}
 ```
@@ -145,13 +79,13 @@ jobs:
       contents: read
       packages: write # allow GITHUB_TOKEN to publish packages
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: actions/setup-node@v3
         with:
-          node-version: "18"
+          node-version: "20"
       - run: npm ci
       - run: npm test
-      - uses: JS-DevTools/npm-publish@v2
+      - uses: JS-DevTools/npm-publish@v3
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           registry: "https://npm.pkg.github.com"
@@ -161,7 +95,7 @@ jobs:
 [npm authentication token]: https://docs.npmjs.com/creating-and-viewing-authentication-tokens
 [GitHub Package Registry]: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry
 
-### Usage
+### Action usage
 
 You can set any or all of the following input parameters using `with`:
 
@@ -184,19 +118,19 @@ You can set any or all of the following input parameters using `with`:
 [npm-access]: https://docs.npmjs.com/cli/v9/commands/npm-publish#access
 [provenance]: https://docs.npmjs.com/generating-provenance-statements
 
-### Output
+### Action output
 
-npm-publish exposes some output variables, which you can use in later steps of your workflow. To access the output variables, you'll need to set an `id` for the npm-publish step.
+npm-publish exposes several output variables, which you can use in later steps of your workflow if you provide an `id` for the npm-publish step.
 
-```yaml
-steps:
-  - id: publish
-    uses: JS-DevTools/npm-publish@v2
-    with:
-      token: ${{ secrets.NPM_TOKEN }}
+```diff
+  steps:
+    - uses: JS-DevTools/npm-publish@v3
++     id: publish
+      with:
+        token: ${{ secrets.NPM_TOKEN }}
 
-  - if: ${{ steps.publish.outputs.type }}
-    run: echo "Version changed!"
++   - if: ${{ steps.publish.outputs.type }}
++     run: echo "Version changed!"
 ```
 
 | Name          | Type    | Description                                                                                                   |
@@ -232,7 +166,7 @@ await npmPublish({ token: "YOUR_NPM_AUTH_TOKEN_HERE" });
 
 [npm]: https://docs.npmjs.com/about-npm/
 
-### Usage
+### API usage
 
 As shown in the example above, you should pass an options object to the `npmPublish` function. In TypeScript, the `Options` interface is available as an import.
 
@@ -257,7 +191,7 @@ import type { Options } from "@jsdevtools/npm-publish";
 1. May be specified using `publishConfig` in `package.json`.
 2. Provenance requires npm `>=9.5.0`.
 
-### Output
+### API output
 
 The `npmPublish()` function returns a promise of a `Results` object. In TypeScript, the `Results` interface is available as an import.
 
@@ -301,7 +235,7 @@ npx npm-publish --token YOUR_NPM_AUTH_TOKEN_HERE --registry http://example.com .
 
 Run `npm-publish --help` to see the full list of options available.
 
-```
+```text
 Usage:
 
   npm-publish <options> [package]
@@ -346,6 +280,116 @@ Examples:
   $ npm-publish --token abc123 ./my-package
 ```
 
+## Migration guides
+
+Major releases of the action and libraries may contain breaking changes, documented here.
+For more detailed change logs, see [releases][].
+
+### v2 to v3
+
+The v3 release does not require any changes to how you use `npm-publish` from `v2`. The version of Node.js used by the action was updated to v20 due to GitHub Action's [deprecation of Node.js v16][node16-deprecation]. The minimum required version of Node.js for the library and CLI remains v16.
+
+[node16-deprecation]: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/
+
+### v1 to v3
+
+The v2 release made several breaking changes to inputs, outputs, and behaviors that were present in `v1`. The examples below focus on the action, but the same changes are applicable to the library and CLI, too.
+
+#### v2 option changes
+
+The `check-version` and `greater-version-only` boolean options were replaced with the `strategy` option:
+
+- `strategy: all` (default) will publish any version that does not yet exist in the registry
+- `strategy: upgrade` will publish only if the version is a semver upgrade of the requested `dist-tag`
+
+```diff
+  with:
+    token: ${{ secrets.NPM_TOKEN }}
+-   check-version: true
+-   greater-version-only: false
++   strategy: all
+
+  with:
+    token: ${{ secrets.NPM_TOKEN }}
+-   check-version: true
+-   greater-version-only: true
++   strategy: upgrade
+```
+
+`check-version: false` has been removed. If you only need to publish, without first checking whether the version exists in the registry, you can [use `npm` directly][publishing-nodejs-packages] instead:
+
+```diff
+  - uses: actions/setup-node@v3
+    with:
+      node-version: '18'
++     registry-url: https://registry.npmjs.org/
+
+- - uses: JS-DevTools/npm-publish@v1
+-   with:
+-     token: ${{ secrets.NPM_TOKEN }}
+-     check-version: false
++ - run: npm publish
++   env:
++     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+[publishing-nodejs-packages]: https://docs.github.com/actions/publishing-packages/publishing-nodejs-packages
+
+#### v2 output changes
+
+The `type` output is now an empty string instead of `'none'` when no release occurs
+
+```diff
+  - run: echo "Version changed!"
+-   if: ${{ steps.publish.outputs.type != 'none' }}
++   if: ${{ steps.publish.outputs.type }}
+```
+
+#### v2 behavior changes
+
+The `--ignore-scripts` option is now passed to `npm publish` as a security precaution. If you define any publish lifecycle scripts - `prepublishOnly`, `prepack`, `prepare`, `postpack`, `publish`, `postpublish` - we recommend you run that logic as a separate explicit build step.
+
+```diff
++ - run: npm run build
+
+- - uses: JS-DevTools/npm-publish@v1
++ - uses: JS-DevTools/npm-publish@v3
+    with:
+      token: ${{ secrets.NPM_TOKEN }}
+```
+
+If you can't change your build, you can set the `ignore-scripts` input to `false` as a workaround. Be aware that failures during a lifecycle script can be difficult to debug, and any `stdout`/`stderr` output from your build script could interfere with how `npm-publish` interprets results from the `npm` CLI.
+
+```diff
+- - uses: JS-DevTools/npm-publish@v1
++ - uses: JS-DevTools/npm-publish@v3
+    with:
+      token: ${{ secrets.NPM_TOKEN }}
++     ignore-scripts: false
+```
+
+The global `.npmrc` file is no longer read nor modified. This means the `token` option is now required for the library and CLI. (It was already required for the action.) You may have workarounds in place referencing `INPUT_TOKEN`, which v1 [erroneously wrote][#15] to `.npmrc`. These workarounds should be removed.
+
+```diff
+  - uses: actions/setup-node@v3
+    with:
+      node-version: '18'
+      registry-url: https://registry.npmjs.org/
+
+- - uses: JS-DevTools/npm-publish@v1
++ - uses: JS-DevTools/npm-publish@v3
+    with:
+      token: ${{ secrets.NPM_TOKEN }}
+
+  - name: Do some more stuff with npm
+    run: npm whoami
+    env:
+-     INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}
++     NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+[#15]: https://github.com/JS-DevTools/npm-publish/issues/15
+
 ## License
 
 npm-publish is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
@@ -359,5 +403,3 @@ Thanks to these awesome companies for their support of Open Source developers
 [![GitHub](https://jstools.dev/img/badges/github.svg)](https://github.com/open-source)
 [![NPM](https://jstools.dev/img/badges/npm.svg)](https://www.npmjs.com/)
 [![Coveralls](https://jstools.dev/img/badges/coveralls.svg)](https://coveralls.io)
-[![Travis CI](https://jstools.dev/img/badges/travis-ci.svg)](https://travis-ci.com)
-[![SauceLabs](https://jstools.dev/img/badges/sauce-labs.svg)](https://saucelabs.com)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jsdevtools/npm-publish",
   "description": "Fast, easy publishing to NPM",
-  "version": "2.2.2",
+  "version": "3.0.0",
   "keywords": [
     "github-action",
     "npm",
@@ -54,31 +54,31 @@
   "devDependencies": {
     "@actions/core": "^1.10.1",
     "@types/command-line-args": "^5.2.1",
-    "@types/node": "^20.6.0",
+    "@types/node": "^20.8.6",
     "@types/tar": "^6.1.6",
-    "@typescript-eslint/eslint-plugin": "^6.7.0",
-    "@typescript-eslint/parser": "^6.7.0",
-    "@vitest/coverage-istanbul": "^0.34.4",
+    "@typescript-eslint/eslint-plugin": "^6.7.5",
+    "@typescript-eslint/parser": "^6.7.5",
+    "@vitest/coverage-istanbul": "^0.34.6",
     "concurrently": "^8.2.1",
-    "esbuild": "^0.19.2",
-    "eslint": "^8.49.0",
+    "esbuild": "^0.19.4",
+    "eslint": "^8.51.0",
     "eslint-config-prettier": "^9.0.0",
-    "eslint-import-resolver-typescript": "^3.6.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "npm:eslint-plugin-i@^2.28.1",
-    "eslint-plugin-jsdoc": "^46.6.0",
-    "eslint-plugin-n": "^16.1.0",
+    "eslint-plugin-jsdoc": "^46.8.2",
+    "eslint-plugin-n": "^16.2.0",
     "eslint-plugin-promise": "^6.1.1",
     "eslint-plugin-sonarjs": "^0.21.0",
     "eslint-plugin-unicorn": "^48.0.1",
     "prettier": "^3.0.3",
-    "prettier-plugin-jsdoc": "^1.0.2",
-    "rimraf": "^5.0.1",
+    "prettier-plugin-jsdoc": "^1.1.1",
+    "rimraf": "^5.0.5",
     "typescript": "^5.2.2",
-    "vitest": "^0.34.4",
-    "vitest-when": "^0.1.2"
+    "vitest": "^0.34.6",
+    "vitest-when": "^0.2.0"
   },
   "dependencies": {
-    "@types/semver": "^7.5.1",
+    "@types/semver": "^7.5.2",
     "command-line-args": "^5.2.1",
     "semver": "7.5.4",
     "tar": "6.2.0"