From e3c9bb8bd47d4df3b9a05ac8dcff7ba22906a012 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stephan=20B=C3=B6nnemann?= Date: Sat, 27 Jan 2018 14:32:24 +0100 Subject: [PATCH] docs: recommend to execute semantic-release via npx --- docs/recipes/gitlab-ci.md | 10 +--------- docs/recipes/travis.md | 25 +++---------------------- docs/support/FAQ.md | 8 +++++++- docs/support/node-version.md | 25 ++++--------------------- docs/usage/installation.md | 24 ++++++++++-------------- 5 files changed, 25 insertions(+), 67 deletions(-) diff --git a/docs/recipes/gitlab-ci.md b/docs/recipes/gitlab-ci.md index 2a42d4ee..661352d6 100644 --- a/docs/recipes/gitlab-ci.md +++ b/docs/recipes/gitlab-ci.md @@ -47,12 +47,7 @@ publish: image: node:8 stage: release script: - # Only for a local semantic-release installation - - npm run semantic-release - - # Only for a global semantic-release installation - - npm install -g semantic-release - - semantic-release + - npx semantic-release ``` ### `package.json` configuration @@ -63,9 +58,6 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins { "devDependencies": { "semantic-release": "^12.0.0" - }, - "scripts": { - "semantic-release": "semantic-release" } } ``` diff --git a/docs/recipes/travis.md b/docs/recipes/travis.md index 54152b0c..b0cfffd5 100644 --- a/docs/recipes/travis.md +++ b/docs/recipes/travis.md @@ -20,8 +20,6 @@ It's recommended to run the `semantic-release` command in the [Travis `deploy` s **Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066). -**Note**: The`semantic-release` execution command varies depending if you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) semantic-release installation. - ```yaml language: node_js @@ -35,10 +33,7 @@ deploy: provider: script skip_cleanup: true script: - # Only for a local semantic-release installation - - npm run semantic-release - # Only for a global semantic-release installation - - npm install -g semantic-release && semantic-release + - npx semantic-release ``` ### `package.json` configuration for single Node job @@ -49,9 +44,6 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins { "devDependencies": { "semantic-release": "^11.0.0" - }, - "scripts": { - "semantic-release": "semantic-release" } } ``` @@ -72,8 +64,6 @@ It's recommended to run the `semantic-release` command in the [Travis `deploy` s **Note**: It's not recommended to run the `semantic-release` command in the Travis `script` step as each script in this step will be executed regardless of the outcome of the previous one. See [travis-ci/travis-ci#1066](https://github.com/travis-ci/travis-ci/issues/1066). -**Note**: The`semantic-release` execution command varies depending if you are using a [local](../usage/installation.md#local-installation) or [global](../usage/installation.md#global-installation) **semantic-release** installation. - ```yaml language: node_js @@ -94,10 +84,7 @@ deploy: provider: script skip_cleanup: true script: - # Only for a local semantic-release installation - - npm run travis-deploy-once "npm run semantic-release" - # Only for a global semantic-release installation - - npm install -g travis-deploy-once semantic-release && travis-deploy-once "semantic-release" + - npx travis-deploy-once "npx semantic-release" ``` **Note**: See the `travis-deploy-once` [`pro`](https://github.com/semantic-release/travis-deploy-once#-p---pro) and [`travis-url`](https://github.com/semantic-release/travis-deploy-once#-u---travis-url) options for using with [Travis Pro](https://docs.travis-ci.com/user/travis-pro) and [Travis Enterprise](https://enterprise.travis-ci.com). @@ -111,10 +98,6 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins "devDependencies": { "semantic-release": "^12.0.0", "travis-deploy-once": "^4.0.0" - }, - "scripts": { - "semantic-release": "semantic-release", - "travis-deploy-once": "travis-deploy-once" } } ``` @@ -156,10 +139,8 @@ deploy: script: # Use nvm to install and use the Node LTS version (nvm is installed on all Travis images) - nvm install lts/* - # Install travis-deploy-once and semantic-release - - npm install -g travis-deploy-once semantic-release # Run semantic-release only on job, after all other are successful - - travis-deploy-once "semantic-release" + - npx travis-deploy-once "npx semantic-release" ``` **Note**: See the `travis-deploy-once` [`pro`](https://github.com/semantic-release/travis-deploy-once#-p---pro) and [`travis-url`](https://github.com/semantic-release/travis-deploy-once#-u---travis-url) options for using with [Travis Pro](https://docs.travis-ci.com/user/travis-pro) and [Travis Enterprise](https://enterprise.travis-ci.com). diff --git a/docs/support/FAQ.md b/docs/support/FAQ.md index 88c40122..94ee30a4 100644 --- a/docs/support/FAQ.md +++ b/docs/support/FAQ.md @@ -64,7 +64,7 @@ See the [CI configuration recipes](../usage/ci-configuration.md) for more detail Yes, you can by explicitly setting the [`--no-ci` CLI option](../usage/configuration.md#options) option. You will also have to set the required [authentication](../usage/ci-configuration.md#authentication) via environment variables on your local machine, for example: ```bash -$ NPM_TOKEN= GH_TOKEN= npm run semantic-release --no-ci +$ NPM_TOKEN= GH_TOKEN= npx semantic-release --no-ci ``` However this is not the recommended approach, as running unit and integration tests on an independent machine before publishing software is a crucial part of the release workflow. @@ -156,3 +156,9 @@ In addition the [verify conditions step](../../README.md#release-steps) verifies **semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which **requires Node version 8.3 or higher**. See [Node version requirement](../support/node-version.md#node-version-requirement) for more details and solutions. + +# What is npx? + +[`npx`](https://www.npmjs.com/package/npx) – short for "npm exec" – is a CLI to find and execute npm binaries within the local `node_modules` folder or in the $PATH. If a binary can't be located npx will download the required package and execute it from its cache location. +The tool is bundled with [npm](https://www.npmjs.com/package/npm) >= 5.2, or can be installed via `npm install -g npx`. +For more details and motivation read the [introductory blog post](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) by [@zkat](https://github.com/zkat). diff --git a/docs/support/node-version.md b/docs/support/node-version.md index d6ae8b93..542af90b 100644 --- a/docs/support/node-version.md +++ b/docs/support/node-version.md @@ -18,35 +18,18 @@ See [CI configuration](../usage/ci-configuration.md) and [CI configuration recip ### Use `npx` -[`npx`](https://github.com/zkat/npx) is a CLI to execute npm binaries. It is bundled with [npm](https://www.npmjs.com/package/npm) >= 5.4, or can be installed via `npm install -g npx`. - -`npx` can be used to download the latest [Node 8 package published on npm](https://www.npmjs.com/package/node) and use it to execute the `semantic-release` command. - -If you are using a [local](../usage/installation.md#local-installation) **semantic-release** installation: +`npx` is included with npm >= 5.2 and can be used to download the latest [Node 8 package published on npm](https://www.npmjs.com/package/node). Use it to execute the `semantic-release` command. ```bash -$ npm install -g npx && npx -p node@8 -c "npm run semantic-release" +$ npx -p node@8 -c "npx semantic-release" ``` -If you are using a [global](../usage/installation.md#global-installation) **semantic-release** installation: - -```bash -# For global semantic-release install -$ npm install -g semantic-release npx && npx -p node@8 -c "semantic-release" -``` +**Note:**: See [What is npx](./FAQ.md#what-is-npx) for more details. ### Use `nvm` If your CI environment provides [nvm](https://github.com/creationix/nvm) you can use it to switch to Node 8 before running the `semantic-release` command. -If you are using a [local](../usage/installation.md#local-installation) **semantic-release** installation: - ```bash -$ nvm install 8 && npm run semantic-release -``` - -If you are using a [global](../usage/installation.md#global-installation) **semantic-release** installation: - -```bash -$ nvm install 8 && npm install -g semantic-release && semantic-release +$ nvm install 8 && npx semantic-release ``` diff --git a/docs/usage/installation.md b/docs/usage/installation.md index 3bb3b90d..ed130459 100644 --- a/docs/usage/installation.md +++ b/docs/usage/installation.md @@ -2,32 +2,28 @@ ## Local installation -For [Node modules projects](https://docs.npmjs.com/getting-started/creating-node-modules) we recommend to install **semantic-release** locally and to run the `semantic-release` command with a [npm script](https://docs.npmjs.com/misc/scripts): +For [Node modules projects](https://docs.npmjs.com/getting-started/creating-node-modules) we recommend to install **semantic-release** locally and to run the `semantic-release` command with [npx](https://www.npmjs.com/package/npx): ```bash $ npm install --save-dev semantic-release ``` -In your `package.json`: - -```json -"scripts": { - "semantic-release": "semantic-release" -} -``` - Then in the CI environment: ```bash -$ npm run semantic-release +$ npx semantic-release ``` +**Note:**: `npx` is a tool bundled with `npm@>=5.2.0`. It is used to conveniently find the semantic-release binary and to execute it. See [What is npx](../support/FAQ.md#what-is-npx) for more details. + ## Global installation -For other type of projects we recommend to install **semantic-release** globally directly in the CI environment: +For other type of projects we recommend to install **semantic-release** directly in the CI environment, also with [npx](https://www.npmjs.com/package/npx): ```bash -$ npm install -g semantic-release -$ semantic-release +$ npx semantic-release ``` -**Note:**: For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with with `npm install -g semantic-release@12`). This way your build will not automatically use the next major **semantic-release** release that could possibly break your build. You will have to upgrade manually when a new major version is released. + +**Note:**: For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with with `npx semantic-release@12`, or `npm install -g semantic-release@12`). This way your build will not automatically use the next major **semantic-release** release that could possibly break your build. You will have to upgrade manually when a new major version is released. + +**Note:**: `npx` is a tool bundled with `npm@>=5.2.0`. It is used to conveniently install the semantic-release binary and to execute it. See [What is npx](../support/FAQ.md#what-is-npx) for more details.