Merge branch 'master' of https://github.com/semantic-release/semantic-release into 20210719-upstream

Author: JoA-MoS

.github/workflows/release.yml

@@ -14,7 +14,9 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
-      - uses: bahmutov/npm-install@v1
+        with:
+          cache: npm
+      - run: npm ci
       - run: npx semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -31,9 +31,10 @@ jobs:
         uses: actions/setup-node@v2
         with:
           node-version: ${{ matrix.node-version }}
+          cache: npm
       - name: Ensure dependencies are compatible with the version of node
         run: echo 'engine-strict=true' >> .npmrc
-      - uses: bahmutov/npm-install@v1
+      - run: npm ci
       - run: npm run test:ci
 
   # separate job to set as required in branch protection,
@@ -44,5 +45,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
-      - uses: bahmutov/npm-install@v1
+        with:
+          cache: npm
+      - run: npm ci
       - run: npm run lint

docs/recipes/circleci-workflows.md

@@ -10,46 +10,39 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
 
 ### `.circleci/config.yml` configuration for multiple Node jobs
 
-This example is a minimal configuration for **semantic-release** with a build running Node 6 and 8. See [CircleCI documentation](https://circleci.com/docs/2.0) for additional configuration options.
+This example is a minimal configuration for **semantic-release** with tests running against Node 16 and 14. See [CircleCI documentation](https://circleci.com/docs/2.0) for additional configuration options.
 
-This example create the workflows `test_node_4`, `test_node_6`, `test_node_8` and `release`. The release workflows will [run `semantic-release` only after the all the `test_node_*` are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+In this example, the [`circleci/node`](https://circleci.com/developer/orbs/orb/circleci/node) orb is imported (Which makes some node operations easier), then a `release` job is defined which will run `semantic-release`.
+
+To run our `release` job, we have created a workflow named `test_and_release` which will run two jobs, `node/test`, which comes from the node orb and will test our application, and our release job. Here, we are actually making use of [matrix jobs](https://circleci.com/blog/circleci-matrix-jobs/) so that our single `node/test` job will actually be executed twice, once for Node version 16, and once for version 14. Finally, we call our release job with a `requires` parameter so that `release` will only run after `node/test` has successfully tested against v14 and v16.
 
 ```yaml
-version: 2
+version: 2.1
+orbs:
+  node: circleci/[email protected]
 jobs:
-  test_node_6:
-    docker:
-      - image: circleci/node:6
-    steps:
-      # Configure your test steps here (checkout, npm install, cache management, tests etc...)
-
-  test_node_8:
-    docker:
-      - image: circleci/node:8
-    steps:
-      # Configure your test steps here (checkout, npm install, cache management, tests etc...)
-
   release:
-    docker:
-      - image: circleci/node:8
+    executor: node/default
     steps:
       - checkout
-      - run: npm install
+      - node/install-packages # Install and automatically cache packages
       # Run optional required steps before releasing
       # - run: npm run build-script
       - run: npx semantic-release
 
 workflows:
-  version: 2
   test_and_release:
     # Run the test jobs first, then the release only when all the test jobs are successful
     jobs:
-      - test_node_6
-      - test_node_8
+      - node/test:
+          matrix:
+            parameters:
+              version:
+                - 16.1.0
+                - 14.7.0
       - release:
           requires:
-            - test_node_6
-            - test_node_8
+            - node/test
 ```
 
 ### `package.json` configuration for multiple Node jobs

docs/recipes/maintenance-releases.md

@@ -33,7 +33,7 @@ The Git history of the repository is now:
 
 One of our users request a new feature, however they cannot migrate to Node.js 8 or higher due to corporate policies.
 
-If we were to push that feature on `master` and release it, the new version would require Node.js 8 or higher as the release would also contains the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
+If we were to push that feature on `master` and release it, the new version would require Node.js 8 or higher as the release would also contain the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
 
 Instead, we create the branch `1.x` from the tag `v1.0.0` with the command `git checkout -b 1.x v1.0.0` and we commit that feature with the message `feat: a feature` to the branch `1.x`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@release-1.x` so users who can't migrate to Node.js 8 or higher can benefit from it.
 
@@ -48,7 +48,7 @@ The Git history of the repository is now:
 
 ## Releasing a bug fix for version 1.0.x users
 
-Another user currently using version `1.0.0` reports a bug. They cannot migrate to Node.js 8 or higher and they also cannot migrate to `1.1.0` as they do not use the feature developed in `feat: a feature` and their corporate policies require to go through a costly quality insurance process for each `minor` upgrades.
+Another user currently using version `1.0.0` reports a bug. They cannot migrate to Node.js 8 or higher and they also cannot migrate to `1.1.0` as they do not use the feature developed in `feat: a feature` and their corporate policies require to go through a costly quality assurance process for each `minor` upgrades.
 
 In order to deliver the bug fix in a `patch` release, we create the branch `1.0.x` from the tag `v1.0.0` with the command `git checkout -b 1.0.x v1.0.0` and we commit that fix with the message `fix: a fix` to the branch `1.0.x`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@release-1.0.x` so users who can't migrate to `1.1.x` or `2.x` can benefit from it.
 

docs/usage/plugins.md

@@ -16,6 +16,8 @@ A plugin is a npm module that can implement one or more of the following steps:
 | `success`          | No       | Responsible for notifying of a new release.                                                                                                                                                                          |
 | `fail`             | No       | Responsible for notifying of a failed release.                                                                                                                                                                       |
 
+Release steps will run in that order. At each step, **semantic-release** will run every plugin in the [`plugins` array](#plugins-declaration-and-execution-order), as long as the plugin implements the step.
+
 **Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used.
 
 ## Plugins installation
@@ -70,6 +72,8 @@ With this configuration **semantic-release** will:
 - execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git`
 - execute the `publish` implementation of `@semantic-release/npm`
 
+Order is first determined by release steps (such as `verifyConditions` → `anayzeCommits`). At each release step, plugins are executed in the order in which they are defined.
+
 ## Plugin options configuration
 
 A plugin configuration can be specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.

docs/usage/workflow-configuration.md

@@ -13,7 +13,7 @@ Each branch can be defined either as a string, a [glob](https://github.com/micro
 
 A branch can defined as one of three types:
 - [release](#release-branches): to make releases on top of the last version released
-- [maintenance](#maintenance-branches): to make release on top of an old release
+- [maintenance](#maintenance-branches): to make releases on top of an old release
 - [pre-release](#pre-release-branches): to make pre-releases
 
 The type of the branch is automatically determined based on naming convention and/or [properties](#branches-properties).
@@ -25,7 +25,7 @@ The type of the branch is automatically determined based on naming convention an
 | `name`       | All                                       | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name).                                                                                 | - The value itself if defined as a `String` or the matching branches name if defined as a glob. |
 | `channel`    | All                                       | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones.              |
 | `range`      | [maintenance](#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](#range).   | The value of `name`.                                                                            |
-| `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release detonation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease).                                 | -                                                                                               |
+| `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release denotation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease).                                 | -                                                                                               |
 
 ### name
 

package-lock.json

@@ -59,7 +59,7 @@
     "file-url": "3.0.0",
     "fs-extra": "10.0.0",
     "got": "11.8.2",
-    "js-yaml": "3.14.1",
+    "js-yaml": "4.1.0",
     "mockserver-client": "5.11.2",
     "nock": "13.1.1",
     "nyc": "15.1.0",

package.json

@@ -136,7 +136,7 @@ test('Read options from .releaserc.yml', async (t) => {
     plugins: false,
   };
   // Create package.json in repository root
-  await writeFile(path.resolve(cwd, '.releaserc.yml'), yaml.safeDump(options));
+  await writeFile(path.resolve(cwd, '.releaserc.yml'), yaml.dump(options));
 
   const {options: result} = await t.context.getConfig({cwd});