docs: recommend to execute semantic-release via npx
This commit is contained in:
Stephan Bönnemann
Gregor Martynus
parent
467635bc14
commit
e3c9bb8bd4
@ -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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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=<your_npm_token> GH_TOKEN=<your_github_token> npm run semantic-release --no-ci
|
||||
$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_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).
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user