diff --git a/docs/developer-guide/js-api.md b/docs/developer-guide/js-api.md index 2fce666b..4857447c 100644 --- a/docs/developer-guide/js-api.md +++ b/docs/developer-guide/js-api.md @@ -142,7 +142,7 @@ Information related to the last release found: | gitTag | `String` | The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) associated with the last release. | | channel | `String` | The distribution channel on which the last release was initially made available (`undefined` for the default distribution channel). | -**Notes**: If no previous release is found, `lastRelease` will be an empty `Object`. +**Note**: If no previous release is found, `lastRelease` will be an empty `Object`. Example: diff --git a/docs/usage/installation.md b/docs/usage/installation.md index 8bcb4597..140f686c 100644 --- a/docs/usage/installation.md +++ b/docs/usage/installation.md @@ -24,9 +24,28 @@ For other type of projects we recommend installing **semantic-release** directly $ npx semantic-release ``` -**Note**: For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with `npx semantic-release@18`). -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. +### Notes -**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. +1. If you've globally installed **semantic-release** then we recommend that you set the major **semantic-release** version to install. + For example, by using `npx semantic-release@18`. + This way you control which major version of **semantic-release** is used by your build, and thus avoid breaking the build when there's a new major version of **semantic-release**. + This also means you, or a bot, must upgrade **semantic-release** when a new major version is released. +2. Pinning **semantic-release** to an exact version makes your releases even more deterministic. + But pinning also means you, or a bot, must update to newer versions of **semantic-release** more often. +3. You can use [Renovate's regex manager](https://docs.renovatebot.com/modules/manager/regex/) to get automatic updates for **semantic-release** in either of the above scenarios. + Put this in your Renovate configuration file: + ```json + { + "regexManagers": [ + { + "description": "Update semantic-release version used by npx", + "fileMatch": ["^\\.github/workflows/[^/]+\\.ya?ml$"], + "matchStrings": ["\\srun: npx semantic-release@(?.*?)\\s"], + "datasourceTemplate": "npm", + "depNameTemplate": "semantic-release" + } + ] + } + ``` +4. `npx` is a tool bundled with `npm@>=5.2.0`. You can use it to install (and run) the **semantic-release** binary. + See [What is npx](../support/FAQ.md#what-is-npx) for more details.