semantic-release 13.2.0 → 13.4.1

package/README.md

@@ -37,10 +37,11 @@ This removes the immediate connection between human emotions and version numbers
 - Fully automated release
 - Enforce [Semantic Versioning](https://semver.org) specification
 - New features and fixes are immediately available to users
+- Notify maintainers and users of new releases
 - Use formalized commit message convention to document changes in the codebase
 - Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
 - Avoid potential errors associated with manual releases
-- Support any  [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
+- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
 - Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
 
 ## How does it work?
@@ -67,7 +68,7 @@ Here is an example of the release type that will be done based on a commit messa
 
 ### Triggering a release
 
-When pushing new commits to the release branch (i.e. `master`) with `git push` or by merging a pull request or merging from another branch, a CI build is triggered and runs the `semantic-release` command to make a release if there is relevant codebase changes since the last release.
+When pushing new commits to the release branch (i.e. `master`) with `git push` or by merging a pull request or merging from another branch, a CI build is triggered and runs the `semantic-release` command to make a release if there are relevant codebase changes since the last release.
 
 By default a release will be done for each push to the release branch that contains relevant code changes. If you need more control over the timing of releases you have a couple of options:
 - Publish releases on a distribution channel (for example npm’s [dist-tags](https://docs.npmjs.com/cli/dist-tag)). This way you can keep control over what your users end up using by default, and you can decide when to make an automatically released version available to the stable channel, and promote it.
@@ -86,6 +87,7 @@ After running the tests the command `semantic-release` will execute the followin
 | Generate notes    | Generate release notes with the [generate notes plugin](docs/usage/plugins.md#generatenotes-plugin) for the commits added since the last release.                     |
 | Create Git tag    | Create a Git tag corresponding the new release version                                                                                                                |
 | Publish           | Publish the release with the [publish plugins](docs/usage/plugins.md#publish-plugin).                                                                                 |
+| Notify            | Notify of new releases or errors with the [success](docs/usage/plugins.md#success-plugin) and [fail](docs/usage/plugins.md#fail-plugin) plugins.                      |
 
 ## Documentation
 

package/cli.js

@@ -1,59 +1,64 @@
-const program = require('commander');
 const {pickBy, isUndefined} = require('lodash');
 
-function list(values) {
-  return values.split(',').map(value => value.trim());
-}
+const stringList = {
+  type: 'string',
+  array: true,
+  coerce: values =>
+    values.length === 1 && values[0].trim() === 'false'
+      ? []
+      : values.reduce((values, value) => values.concat(value.split(',').map(value => value.trim())), []),
+};
 
 module.exports = async () => {
-  program
-    .name('semantic-release')
-    .description('Run automated package publishing')
-    .option('-b, --branch <branch>', 'Branch to release from')
-    .option('-r, --repository-url <repositoryUrl>', 'Git repository URL')
-    .option('-t, --tag-format <tagFormat>', `Git tag format`)
-    .option('-e, --extends <paths>', 'Comma separated list of shareable config paths or packages name', list)
-    .option(
-      '--verify-conditions <paths>',
-      'Comma separated list of paths or packages name for the verifyConditions plugin(s)',
-      list
-    )
-    .option('--analyze-commits <path>', 'Path or package name for the analyzeCommits plugin')
-    .option(
-      '--verify-release <paths>',
-      'Comma separated list of paths or packages name for the verifyRelease plugin(s)',
-      list
-    )
-    .option('--generate-notes <path>', 'Path or package name for the generateNotes plugin')
-    .option('--publish <paths>', 'Comma separated list of paths or packages name for the publish plugin(s)', list)
-    .option(
-      '--no-ci',
-      'Skip Continuous Integration environment verifications, allowing to make releases from a local machine'
-    )
-    .option('--debug', 'Output debugging information')
-    .option(
-      '-d, --dry-run',
-      'Dry-run mode, skipping verifyConditions, publishing and release, printing next version and release notes'
-    )
-    .parse(process.argv);
-
-  if (program.debug) {
-    // Debug must be enabled before other requires in order to work
-    require('debug').enable('semantic-release:*');
-  }
+  const cli = require('yargs')
+    .command('$0', 'Run automated package publishing', yargs => {
+      yargs.demandCommand(0, 0).usage(`Run automated package publishing
+Usage:
+  semantic-release [options] [plugins]`);
+    })
+    .option('b', {alias: 'branch', describe: 'Git branch to release from', type: 'string', group: 'Options'})
+    .option('r', {alias: 'repository-url', describe: 'Git repository URL', type: 'string', group: 'Options'})
+    .option('t', {alias: 'tag-format', describe: 'Git tag format', type: 'string', group: 'Options'})
+    .option('e', {alias: 'extends', describe: 'Shareable configurations', ...stringList, group: 'Options'})
+    .option('ci', {describe: 'Toggle CI verifications', default: true, type: 'boolean', group: 'Options'})
+    .option('verify-conditions', {...stringList, group: 'Plugins'})
+    .option('analyze-commits', {type: 'string', group: 'Plugins'})
+    .option('verify-release', {...stringList, group: 'Plugins'})
+    .option('generate-notes', {type: 'string', group: 'Plugins'})
+    .option('publish', {...stringList, group: 'Plugins'})
+    .option('success', {...stringList, group: 'Plugins'})
+    .option('fail', {...stringList, group: 'Plugins'})
+    .option('debug', {describe: 'Output debugging information', default: false, type: 'boolean', group: 'Options'})
+    .option('d', {alias: 'dry-run', describe: 'Skip publishing', default: false, type: 'boolean', group: 'Options'})
+    .option('h', {alias: 'help', group: 'Options'})
+    .option('v', {alias: 'version', group: 'Options'})
+    .strict(false)
+    .exitProcess(false);
 
   try {
-    if (program.args.length > 0) {
-      program.outputHelp();
-      process.exitCode = 1;
-    } else {
-      const opts = program.opts();
-      // Set the `noCi` options as commander.js sets the `ci` options instead (becasue args starts with `--no`)
-      opts.noCi = opts.ci === false ? true : undefined;
-      // Remove option with undefined values, as commander.js sets non defined options as `undefined`
-      await require('.')(pickBy(opts, value => !isUndefined(value)));
+    const {help, version, ...opts} = cli.argv;
+    if (Boolean(help) || Boolean(version)) {
+      process.exitCode = 0;
+      return;
+    }
+
+    // Set the `noCi` options as yargs sets the `ci` options instead (because arg starts with `--no`)
+    if (opts.ci === false) {
+      opts.noCi = true;
     }
+
+    if (opts.debug) {
+      // Debug must be enabled before other requires in order to work
+      require('debug').enable('semantic-release:*');
+    }
+
+    // Remove option with undefined values, as yargs sets non defined options as `undefined`
+    await require('.')(pickBy(opts, value => !isUndefined(value)));
+    process.exitCode = 0;
   } catch (err) {
+    if (err.name !== 'YError') {
+      console.error(err);
+    }
     process.exitCode = 1;
   }
 };

package/docs/README.md

@@ -1,7 +1,7 @@
 # semantic-release documentation
 
 - [Usage](usage/README.md) - **semantic-release** installation and configuration
-- [Extending][extending/README.md]- Extending **semantic-release** with plugins and shareable configurations
+- [Extending](extending/README.md)- Extending **semantic-release** with plugins and shareable configurations
 - [Recipes](recipes/README.md) - Community written recipes for common **semantic-release** use-cases
 - [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
 - [Resources](resources.md) - Videos, articles and tutorials

package/docs/extending/plugins-list.md

@@ -5,6 +5,8 @@
 - [@semantic-release/github](https://github.com/semantic-release/github)
   - [verifyConditions](https://github.com/semantic-release/github#verifyconditions): Verify the presence and the validity of the GitHub authentication and release configuration
   - [publish](https://github.com/semantic-release/github#publish): Publish a [GitHub release](https://help.github.com/articles/about-releases)
+  - [success](https://github.com/semantic-release/github#success): Add a comment to GitHub issues and pull requests resolved in the release
+  - [fail](https://github.com/semantic-release/github#fail): Open a GitHub issue when a release fails
 - [@semantic-release/npm](https://github.com/semantic-release/npm)
   - [verifyConditions](https://github.com/semantic-release/npm#verifyconditions): Verify the presence and the validity of the npm authentication and release configuration
   - [publish](https://github.com/semantic-release/npm#publish): Publish the package on the npm registry
@@ -25,6 +27,8 @@
   - [analyzeCommits](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to determine the type of release
   - [verifyRelease](https://github.com/semantic-release/exec#verifyrelease): Execute a shell command to verifying a release that was determined before and is about to be published.
   - [generateNotes](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to generate the release note
-  - [publish](https://github.com/semantic-release/exec#publish): Execute a shell command to publish the release.
+  - [publish](https://github.com/semantic-release/exec#publish): Execute a shell command to publish the release
+  - [success](https://github.com/semantic-release/exec#success): Execute a shell command to notify of a new release
+  - [fail](https://github.com/semantic-release/exec#fail): Execute a shell command to notify of a failed release
 
 ## Community plugins

package/docs/recipes/circleci-workflows.md

@@ -1 +1,65 @@
-# CircleCI 2.0 workflows
+# Using semantic-release with [CircleCI 2.0 workflows](https://circleci.com/docs/2.0/workflows)
+
+## Environment variables
+
+The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app)..
+
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/ci-configuration.md#automatic-setup-with-semantic-release-cli).
+
+## Multiple Node jobs configuration
+
+### `.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 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).
+
+```yaml
+version: 2
+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
+    steps:
+      - checkout
+      - run: npm install
+      # 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
+      - release:
+          requires:
+            - test_node_6
+            - test_node_8
+```
+
+### `package.json` configuration for multiple Node jobs
+
+A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+
+```json
+{
+  "devDependencies": {
+    "semantic-release": "^12.0.0"
+  }
+}
+```

package/docs/recipes/gitlab-ci.md

@@ -8,11 +8,11 @@ The [Authentication](../usage/ci-configuration.md#authentication) environment va
 
 GitLab CI supports [Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html) allowing to test on multiple Node versions and publishing a release only when all test pass.
 
-**Note**: The publish pipeline must run a [Node >= 8 version](../support/FAQ.md#why-does-semantic-release-require-node-version--8).
+**Note**: The publish pipeline must run a [Node >= 8 version](../support/FAQ.md#why-does-semantic-release-require-node-version--83).
 
 ### `.gitlab-ci.yml` configuration for Node projects
 
-This example is a minimal configuration for **semantic-release** with a build running Node 4, 6 and 8 on Linux. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
+This example is a minimal configuration for **semantic-release** with a build running Node 6 and 8. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
 
 **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.
 
@@ -25,12 +25,6 @@ stages:
 before_script:
   - npm install
 
-node:4:
-  image: node:4
-  stage: test
-  script:
-    - npm test
-
 node:6:
   image: node:6
   stage: test

package/docs/recipes/travis-build-stages.md

@@ -1 +1,95 @@
 # Using semantic-release with [Travis CI build stages](https://docs.travis-ci.com/user/build-stages)
+
+## Environment variables
+
+The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env).
+
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/ci-configuration.md#automatic-setup-with-semantic-release-cli).
+
+## Multiple Node jobs configuration
+
+### `.travis.yml` configuration for multiple Node jobs
+
+This example is a minimal configuration for **semantic-release** with a build running Node 6 and 8. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
+
+This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+
+It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
+
+**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).
+
+**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
+
+```yaml
+language: node_js
+
+node_js:
+  - 8
+  - 6
+
+jobs:
+  include:
+    # Define the release stage that runs semantic-release
+    - stage: release
+      node_js: lts/*
+      # Advanced: optionally overwrite your default `script` step to skip the tests
+      # script: skip
+      deploy:
+        provider: script
+        skip_cleanup: true
+        script:
+          - npx semantic-release
+```
+
+### `package.json` configuration for multiple Node jobs
+
+A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+
+```json
+{
+  "devDependencies": {
+    "semantic-release": "^12.0.0"
+  }
+}
+```
+
+## Non-JavaScript projects configuration
+
+For projects that require to be tested with one or multiple version of a Non-JavaScript [language](https://docs.travis-ci.com/user/languages), optionally on multiple [Operating Systems](https://docs.travis-ci.com/user/multi-os).
+
+This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
+
+### `.travis.yml` configuration for non-JavaScript projects
+
+This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go). See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
+
+This example creates a `release` [build stage](https://docs.travis-ci.com/user/build-stages) that [runs `semantic-release` only after all test jobs are successful](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+
+It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
+
+**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).
+
+**Advanced configuration**: Running the tests in the `script` step of the `release` stage is not necessary as the previous stage(s) already ran them. To increase speed, the `script` step of the `release` stage can be overwritten to skip the tests. Note that other commands such as build or compilation might still be required.
+
+```yaml
+language: go
+
+go:
+  - 1.6
+  - 1.7
+
+jobs:
+  include:
+    # Define the release stage that runs semantic-release
+    - stage: release
+      # Advanced: optionally overwrite your default `script` step to skip the tests
+      # script:
+      #   - make
+      deploy:
+        provider: script
+        skip_cleanup: true
+        script:
+          # Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
+          - nvm install lts/*
+          - npx semantic-release
+```

package/docs/recipes/travis.md

@@ -10,7 +10,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
 
 For projects that require to be tested only with a single [Node version](https://docs.travis-ci.com/user/getting-started/#Selecting-a-different-programming-language) on [one Operating System](https://docs.travis-ci.com/user/getting-started/#Selecting-infrastructure-(optional)).
 
-**Note**: [Node 8 is the minimal version required](../support/FAQ.md#why-does-semantic-release-require-node-version--8).
+**Note**: [Node 8 is the minimal version required](../support/FAQ.md#why-does-semantic-release-require-node-version--83).
 
 ### `.travis.yml` configuration for single Node job
 
@@ -25,10 +25,6 @@ language: node_js
 
 node_js: 8
 
-script:
-  # Run tests
-  - npm run test
-
 deploy:
   provider: script
   skip_cleanup: true
@@ -56,9 +52,9 @@ For projects that require to be tested with multiple [Node versions](https://doc
 
 ### `.travis.yml` configuration for multiple Node jobs
 
-This example is a minimal configuration for **semantic-release** with a build running Node 4, 6 and 8 on Linux and OSX. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
+This example is a minimal configuration for **semantic-release** with a build running Node 6 and 8. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
 
-This example uses [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once) in order to command [Run `semantic-release` only after all tests succeeded](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). Alternatively you can use [Travis CI Build Stages recipe](travis-build-stages.md).
+This example uses [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once) in order to [Run `semantic-release` only after all tests succeeded](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). Alternatively you can use [Travis CI Build Stages recipe](travis-build-stages.md).
 
 It's recommended to run the `semantic-release` command in the [Travis `deploy` step](https://docs.travis-ci.com/user/customizing-the-build/#The-Build-Lifecycle) so if an error occurs the build will fail and Travis will send a notification.
 
@@ -70,15 +66,6 @@ language: node_js
 node_js:
   - 8
   - 6
-  - 4
-
-os:
-  - linux
-  - osx
-
-script:
-  # Run tests
-  - npm run test
 
 deploy:
   provider: script
@@ -110,7 +97,7 @@ This recipe cover the Travis specifics only. See [Non JavaScript projects recipe
 
 ### `.travis.yml` configuration for non-JavaScript projects
 
-This example is a minimal configuration for semantic-release with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go) on Linux and OSX. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
+This example is a minimal configuration for **semantic-release** with a build running [Go 1.6 and 1.7](https://docs.travis-ci.com/user/languages/go) on Linux and OSX. See [Travis - Customizing the Build](https://docs.travis-ci.com/user/customizing-the-build) for additional configuration options.
 
 This example uses [`travis-deploy-once`](https://github.com/semantic-release/travis-deploy-once) in order to [run `semantic-release` only after all tests succeeded](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded). Alternatively you can use [Travis CI Build Stages recipe](travis-build-stages.md).
 
@@ -129,17 +116,13 @@ os:
   - linux
   - osx
 
-script:
-  # Run tests
-  - go test -v ./...
-
 deploy:
   provider: script
   skip_cleanup: true
   script:
     # Use nvm to install and use the Node LTS version (nvm is installed on all Travis images)
     - nvm install lts/*
-    # Run semantic-release only on job, after all other are successful
+    # Run semantic-release only on one job, after all other are successful
     - npx travis-deploy-once "npx semantic-release"
 ```
 

package/docs/support/FAQ.md

@@ -131,7 +131,7 @@ See [Artifactory - npm Registry](https://www.jfrog.com/confluence/display/RTF/Np
 
 You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a *specific* version release, because this is the whole point of semantic-release.
 
-### Can I exclude commits from the analysis?
+## Can I exclude commits from the analysis?
 
 Yes, every commits that contains `[skip release]` or `[release skip]` in their message will be excluded from the commit analysis and won't participate in the release type determination.
 

package/docs/usage/configuration.md

@@ -59,7 +59,7 @@ Default: `repository` property in `package.json` or [git origin url](https://git
 
 CLI arguments: `-r`, `--repository-url`
 
-The git repository URL
+The git repository URL.
 
 Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)).
 
@@ -75,7 +75,7 @@ CLI arguments: `-t`, `--tag-format`
 
 The [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) format used by **semantic-release** to identify releases. The tag name is generated with [Lodash template](https://lodash.com/docs#template) and will be compiled with the `version` variable.
 
-**Note**: The `tagFormat` must contain the `version` variable and compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description).
+**Note**: The `tagFormat` must contain the `version` variable exactly once and compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description).
 
 ### dryRun
 
@@ -166,3 +166,27 @@ CLI argument: `--publish`
 Define the list of [publish plugins](plugins.md#publish-plugin). Plugins will run in series, in the order defined in the `Array`.
 
 See [Plugins configuration](plugins.md#configuration) for more details.
+
+### success
+
+Type: `Array`, `String`, `Object`
+
+Default: `[]`
+
+CLI argument: `--success`
+
+Define the list of [success plugins](plugins.md#success-plugin). Plugins will run in series, in the order defined in the `Array`.
+
+See [Plugins configuration](plugins.md#configuration) for more details.
+
+### fail
+
+Type: `Array`, `String`, `Object`
+
+Default: `[]`
+
+CLI argument: `--fail`
+
+Define the list of [fail plugins](plugins.md#fail-plugin). Plugins will run in series, in the order defined in the `Array`.
+
+See [Plugins configuration](plugins.md#configuration) for more details.

package/docs/usage/plugins.md

@@ -34,6 +34,18 @@ Plugin responsible for publishing the release.
 
 Default implementation: [npm](https://github.com/semantic-release/npm#publish) and [github](https://github.com/semantic-release/github#publish).
 
+### success plugin
+
+Plugin responsible for notifying of a new release.
+
+Default implementation: [github](https://github.com/semantic-release/github#success).
+
+### fail plugin
+
+Plugin responsible for notifying of a failed release.
+
+Default implementation: [github](https://github.com/semantic-release/github#fail).
+
 ## Configuration
 
 Plugin can be configured by specifying the plugin's module name or file path directly as a `String` or within the `path` key of an `Object`.

package/index.js

@@ -1,21 +1,23 @@
-const {template} = require('lodash');
+const {template, isPlainObject, castArray} = require('lodash');
 const marked = require('marked');
 const TerminalRenderer = require('marked-terminal');
 const envCi = require('env-ci');
 const hookStd = require('hook-std');
+const pkg = require('./package.json');
 const hideSensitive = require('./lib/hide-sensitive');
 const getConfig = require('./lib/get-config');
 const verify = require('./lib/verify');
 const getNextVersion = require('./lib/get-next-version');
 const getCommits = require('./lib/get-commits');
 const getLastRelease = require('./lib/get-last-release');
+const {extractErrors} = require('./lib/utils');
 const logger = require('./lib/logger');
 const {unshallow, gitHead: getGitHead, tag, push, deleteTag} = require('./lib/git');
 
-async function run(opts) {
+marked.setOptions({renderer: new TerminalRenderer()});
+
+async function run(options, plugins) {
   const {isCi, branch, isPr} = envCi();
-  const config = await getConfig(opts, logger);
-  const {plugins, options} = config;
 
   if (!isCi && !options.dryRun && !options.noCi) {
     logger.log('This run was not triggered in a known CI environment, running in dry-run mode.');
@@ -34,7 +36,7 @@ async function run(opts) {
   logger.log('Run automated release from branch %s', options.branch);
 
   logger.log('Call plugin %s', 'verify-conditions');
-  await plugins.verifyConditions({options, logger}, true);
+  await plugins.verifyConditions({options, logger}, {settleAll: true});
 
   // Unshallow the repo in order to get all the tags
   await unshallow();
@@ -57,14 +59,13 @@ async function run(opts) {
   const nextRelease = {type, version, gitHead: await getGitHead(), gitTag: template(options.tagFormat)({version})};
 
   logger.log('Call plugin %s', 'verify-release');
-  await plugins.verifyRelease({options, logger, lastRelease, commits, nextRelease}, true);
+  await plugins.verifyRelease({options, logger, lastRelease, commits, nextRelease}, {settleAll: true});
 
   const generateNotesParam = {options, logger, lastRelease, commits, nextRelease};
 
   if (options.dryRun) {
     logger.log('Call plugin %s', 'generate-notes');
     const notes = await plugins.generateNotes(generateNotesParam);
-    marked.setOptions({renderer: new TerminalRenderer()});
     logger.log('Release note for version %s:\n', nextRelease.version);
     process.stdout.write(`${marked(notes)}\n`);
   } else {
@@ -77,45 +78,86 @@ async function run(opts) {
     await push(options.repositoryUrl, branch);
 
     logger.log('Call plugin %s', 'publish');
-    await plugins.publish({options, logger, lastRelease, commits, nextRelease}, false, async prevInput => {
-      const newGitHead = await getGitHead();
-      // If previous publish plugin has created a commit (gitHead changed)
-      if (prevInput.nextRelease.gitHead !== newGitHead) {
-        // Delete the previously created tag
-        await deleteTag(options.repositoryUrl, nextRelease.gitTag);
-        // Recreate the tag, referencing the new gitHead
-        logger.log('Create tag %s', nextRelease.gitTag);
-        await tag(nextRelease.gitTag);
-        await push(options.repositoryUrl, branch);
-
-        nextRelease.gitHead = newGitHead;
-        // Regenerate the release notes
-        logger.log('Call plugin %s', 'generateNotes');
-        nextRelease.notes = await plugins.generateNotes(generateNotesParam);
+    const releases = await plugins.publish(
+      {options, logger, lastRelease, commits, nextRelease},
+      {
+        getNextInput: async lastResult => {
+          const newGitHead = await getGitHead();
+          // If previous publish plugin has created a commit (gitHead changed)
+          if (lastResult.nextRelease.gitHead !== newGitHead) {
+            // Delete the previously created tag
+            await deleteTag(options.repositoryUrl, nextRelease.gitTag);
+            // Recreate the tag, referencing the new gitHead
+            logger.log('Create tag %s', nextRelease.gitTag);
+            await tag(nextRelease.gitTag);
+            await push(options.repositoryUrl, branch);
+
+            nextRelease.gitHead = newGitHead;
+            // Regenerate the release notes
+            logger.log('Call plugin %s', 'generateNotes');
+            nextRelease.notes = await plugins.generateNotes(generateNotesParam);
+          }
+          // Call the next publish plugin with the updated `nextRelease`
+          return {options, logger, lastRelease, commits, nextRelease};
+        },
+        // Add nextRelease and plugin properties to published release
+        transform: (release, step) => ({...(isPlainObject(release) ? release : {}), ...nextRelease, ...step}),
       }
-      // Call the next publish plugin with the updated `nextRelease`
-      return {options, logger, lastRelease, commits, nextRelease};
-    });
+    );
+
+    await plugins.success(
+      {options, logger, lastRelease, commits, nextRelease, releases: castArray(releases)},
+      {settleAll: true}
+    );
+
     logger.log('Published release: %s', nextRelease.version);
   }
   return true;
 }
 
+function logErrors(err) {
+  const errors = extractErrors(err).sort(error => (error.semanticRelease ? -1 : 0));
+  for (const error of errors) {
+    if (error.semanticRelease) {
+      logger.log(`%s ${error.message}`, error.code);
+      if (error.details) {
+        process.stdout.write(`${marked(error.details)}\n`);
+      }
+    } else {
+      logger.error('An error occurred while running semantic-release: %O', error);
+    }
+  }
+}
+
+async function callFail(plugins, options, error) {
+  const errors = extractErrors(error).filter(error => error.semanticRelease);
+  if (errors.length > 0) {
+    try {
+      await plugins.fail({options, logger, errors}, {settleAll: true});
+    } catch (err) {
+      logErrors(err);
+    }
+  }
+}
+
 module.exports = async opts => {
+  logger.log(`Running %s version %s`, pkg.name, pkg.version);
   const unhook = hookStd({silent: false}, hideSensitive);
   try {
-    const result = await run(opts);
-    unhook();
-    return result;
-  } catch (err) {
-    const errors = err.name === 'AggregateError' ? Array.from(err).sort(error => !error.semanticRelease) : [err];
-    for (const error of errors) {
-      if (error.semanticRelease) {
-        logger.log(`%s ${error.message}`, error.code);
-      } else {
-        logger.error('An error occurred while running semantic-release: %O', error);
+    const config = await getConfig(opts, logger);
+    const {plugins, options} = config;
+    try {
+      const result = await run(options, plugins);
+      unhook();
+      return result;
+    } catch (err) {
+      if (!options.dryRun) {
+        await callFail(plugins, options, err);
       }
+      throw err;
     }
+  } catch (err) {
+    logErrors(err);
     unhook();
     throw err;
   }

package/lib/definitions/errors.js

@@ -0,0 +1,118 @@
+const url = require('url');
+const {inspect} = require('util');
+const {toLower, isString} = require('lodash');
+const pkg = require('../../package.json');
+const RELEASE_TYPE = require('./release-types');
+
+const homepage = url.format({...url.parse(pkg.homepage), ...{hash: null}});
+const stringify = obj => (isString(obj) ? obj : inspect(obj, {breakLength: Infinity, depth: 2, maxArrayLength: 5}));
+const linkify = file => `${homepage}/blob/caribou/${file}`;
+
+module.exports = {
+  ENOGITREPO: () => ({
+    message: 'Not running from a git repository.',
+    details: `The \`semantic-release\` command must be executed from a Git repository.
+
+The current working directory is \`${process.cwd()}\`.
+
+Please verify your CI configuration to make sure the \`semantic-release\` command is executed from the root of the cloned repository.`,
+  }),
+  ENOREPOURL: () => ({
+    message: 'The `repositoryUrl` option is required.',
+    details: `The [repositoryUrl option](${linkify(
+      'docs/usage/configuration.md#repositoryurl'
+    )}) cannot be determined from the semantic-release configuration, the \`package.json\` nor the [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes).
+
+Please make sure to add the \`repositoryUrl\` to the [semantic-release configuration] (${linkify(
+      'docs/usage/configuration.md'
+    )}).`,
+  }),
+  EGITNOPERMISSION: ({options}) => ({
+    message: 'The push permission to the Git repository is required.',
+    details: `**semantic-release** cannot push the version tag to the branch \`${
+      options.branch
+    }\` on remote Git repository.
+
+Please refer to the [authentication configuration documentation](${linkify(
+      'docs/usage/ci-configuration.md#authentication'
+    )}) to configure the Git credentials on your CI environment.`,
+  }),
+  EINVALIDTAGFORMAT: ({tagFormat}) => ({
+    message: 'Invalid `tagFormat` option.',
+    details: `The [tagFormat](${linkify(
+      'docs/usage/configuration.md#tagformat'
+    )}) must compile to a [valid Git reference](https://git-scm.com/docs/git-check-ref-format#_description).
+
+Your configuration for the \`tagFormat\` option is \`${stringify(tagFormat)}\`.`,
+  }),
+  ETAGNOVERSION: ({tagFormat}) => ({
+    message: 'Invalid `tagFormat` option.',
+    details: `The [tagFormat](${linkify(
+      'docs/usage/configuration.md#tagformat'
+    )}) option must contain the variable \`version\` exactly once.
+
+Your configuration for the \`tagFormat\` option is \`${stringify(tagFormat)}\`.`,
+  }),
+  EPLUGINCONF: ({pluginType, pluginConf}) => ({
+    message: `The \`${pluginType}\` plugin configuration is invalid.`,
+    details: `The [${pluginType} plugin configuration](${linkify(
+      `docs/usage/plugins.md#${toLower(pluginType)}-plugin`
+    )}) if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a \`path\` property.
+
+    Your configuration for the \`${pluginType}\` plugin is \`${stringify(pluginConf)}\`.`,
+  }),
+  EPLUGIN: ({pluginName, pluginType}) => ({
+    message: `A plugin configured in the step ${pluginType} is not a valid semantic-release plugin.`,
+    details: `A valid \`${pluginType}\` **semantic-release** plugin must be a function or an object with a function in the property \`${pluginType}\`.
+
+The plugin \`${pluginName}\` doesn't have the property \`${pluginType}\` and cannot be used for the \`${pluginType}\` step.
+
+Please refer to the \`${pluginName}\` and [semantic-release plugins configuration](${linkify(
+      'docs/usage/plugins.md'
+    )}) documentation for more details.`,
+  }),
+  EANALYZEOUTPUT: ({result, pluginName}) => ({
+    message: 'The `analyzeCommits` plugin returned an invalid value. It must return a valid semver release type.',
+    details: `The \`analyzeCommits\` plugin must return a valid [semver](https://semver.org) release type. The valid values are: ${RELEASE_TYPE.map(
+      type => `\`${type}\``
+    ).join(', ')}.
+
+The \`analyzeCommits\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+  ERELEASENOTESOUTPUT: ({result, pluginName}) => ({
+    message: 'The `generateNotes` plugin returned an invalid value. It must return a `String`.',
+    details: `The \`generateNotes\` plugin must return a \`String\`.
+
+The \`generateNotes\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+  EPUBLISHOUTPUT: ({result, pluginName}) => ({
+    message: 'A `publish` plugin returned an invalid value. It must return an `Object`.',
+    details: `The \`publish\` plugins must return an \`Object\`.
+
+The \`publish\` function of the \`${pluginName}\` returned \`${stringify(result)}\` instead.
+
+We recommend to report the issue to the \`${pluginName}\` authors, providing the following informations:
+- The **semantic-release** version: \`${pkg.version}\`
+- The **semantic-release** logs from your CI job
+- The value returned by the plugin: \`${stringify(result)}\`
+- A link to the **semantic-release** plugin developer guide: [${linkify('docs/developer-guide/plugin.md')}](${linkify(
+      'docs/developer-guide/plugin.md'
+    )})`,
+  }),
+};

package/lib/definitions/plugins.js

@@ -0,0 +1,61 @@
+const {isString, isFunction, isArray, isPlainObject} = require('lodash');
+const RELEASE_TYPE = require('./release-types');
+
+const validatePluginConfig = conf => isString(conf) || isString(conf.path) || isFunction(conf);
+
+module.exports = {
+  verifyConditions: {
+    default: ['@semantic-release/npm', '@semantic-release/github'],
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  analyzeCommits: {
+    default: '@semantic-release/commit-analyzer',
+    config: {
+      validator: conf => Boolean(conf) && validatePluginConfig(conf),
+    },
+    output: {
+      validator: output => !output || RELEASE_TYPE.includes(output),
+      error: 'EANALYZEOUTPUT',
+    },
+  },
+  verifyRelease: {
+    default: false,
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  generateNotes: {
+    default: '@semantic-release/release-notes-generator',
+    config: {
+      validator: conf => !conf || validatePluginConfig(conf),
+    },
+    output: {
+      validator: output => !output || isString(output),
+      error: 'ERELEASENOTESOUTPUT',
+    },
+  },
+  publish: {
+    default: ['@semantic-release/npm', '@semantic-release/github'],
+    config: {
+      validator: conf => Boolean(conf) && (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+    output: {
+      validator: output => !output || isPlainObject(output),
+      error: 'EPUBLISHOUTPUT',
+    },
+  },
+  success: {
+    default: false,
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+  fail: {
+    default: false,
+    config: {
+      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
+    },
+  },
+};

package/lib/definitions/release-types.js

@@ -0,0 +1 @@
+module.exports = ['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'];

package/lib/get-config.js

@@ -4,7 +4,7 @@ const cosmiconfig = require('cosmiconfig');
 const resolveFrom = require('resolve-from');
 const debug = require('debug')('semantic-release:config');
 const {repoUrl} = require('./git');
-const PLUGINS_DEFINITION = require('./plugins/definitions');
+const PLUGINS_DEFINITIONS = require('./definitions/plugins');
 const plugins = require('./plugins');
 const getGitAuthUrl = require('./get-git-auth-url');
 
@@ -25,7 +25,7 @@ module.exports = async (opts, logger) => {
         // For each plugin defined in a shareable config, save in `pluginsPath` the extendable config path,
         // so those plugin will be loaded relatively to the config file
         Object.keys(extendsOpts).reduce((pluginsPath, option) => {
-          if (PLUGINS_DEFINITION[option]) {
+          if (PLUGINS_DEFINITIONS[option]) {
             castArray(extendsOpts[option])
               .filter(plugin => isString(plugin) || (isPlainObject(plugin) && isString(plugin.path)))
               .map(plugin => (isString(plugin) ? plugin : plugin.path))
@@ -42,17 +42,17 @@ module.exports = async (opts, logger) => {
     };
   }
 
-  const repositoryUrl = (await pkgRepoUrl()) || (await repoUrl());
-
   // Set default options values if not defined yet
   options = {
     branch: 'master',
-    repositoryUrl: repositoryUrl ? getGitAuthUrl(repositoryUrl) : repositoryUrl,
+    repositoryUrl: (await pkgRepoUrl()) || (await repoUrl()),
     tagFormat: `v\${version}`,
     // Remove `null` and `undefined` options so they can be replaced with default ones
     ...pickBy(options, option => !isUndefined(option) && !isNull(option)),
   };
 
+  options.repositoryUrl = options.repositoryUrl ? getGitAuthUrl(options.repositoryUrl) : options.repositoryUrl;
+
   debug('options values: %O', options);
 
   return {options, plugins: await plugins(options, pluginsPath, logger)};

package/lib/get-error.js

@@ -0,0 +1,7 @@
+const SemanticReleaseError = require('@semantic-release/error');
+const ERROR_DEFINITIONS = require('./definitions/errors');
+
+module.exports = (code, ctx = {}) => {
+  const {message, details} = ERROR_DEFINITIONS[code](ctx);
+  return new SemanticReleaseError(message, code, details);
+};

package/lib/git.js

@@ -120,7 +120,6 @@ async function push(origin, branch) {
  *
  * @param {String} origin The remote repository URL.
  * @param {String} tagName The tag name to delete.
- * @throws {SemanticReleaseError} if the remote tag exists and references a commit that is not the local head commit.
  */
 async function deleteTag(origin, tagName) {
   // Delete the local tag

package/lib/plugins/index.js

@@ -1,34 +1,35 @@
-const {isArray, isObject, omit} = require('lodash');
+const {isArray, isObject, omit, castArray, isUndefined} = require('lodash');
 const AggregateError = require('aggregate-error');
-const SemanticReleaseError = require('@semantic-release/error');
-const PLUGINS_DEFINITION = require('./definitions');
+const getError = require('../get-error');
+const PLUGINS_DEFINITIONS = require('../definitions/plugins');
 const pipeline = require('./pipeline');
 const normalize = require('./normalize');
 
 module.exports = (options, pluginsPath, logger) => {
   const errors = [];
-  const plugins = Object.keys(PLUGINS_DEFINITION).reduce((plugins, pluginType) => {
-    const {config, output, default: def} = PLUGINS_DEFINITION[pluginType];
+  const plugins = Object.keys(PLUGINS_DEFINITIONS).reduce((plugins, pluginType) => {
+    const {config, default: def} = PLUGINS_DEFINITIONS[pluginType];
     let pluginConfs;
-    if (options[pluginType]) {
+
+    if (isUndefined(options[pluginType])) {
+      pluginConfs = def;
+    } else {
       // If an object is passed and the path is missing, set the default one for single plugins
       if (isObject(options[pluginType]) && !options[pluginType].path && !isArray(def)) {
         options[pluginType].path = def;
       }
       if (config && !config.validator(options[pluginType])) {
-        errors.push(new SemanticReleaseError(config.message, 'EPLUGINCONF'));
+        errors.push(getError('EPLUGINCONF', {pluginType, pluginConf: options[pluginType]}));
         return plugins;
       }
       pluginConfs = options[pluginType];
-    } else {
-      pluginConfs = def;
     }
 
-    const globalOpts = omit(options, Object.keys(PLUGINS_DEFINITION));
+    const globalOpts = omit(options, Object.keys(PLUGINS_DEFINITIONS));
 
-    plugins[pluginType] = isArray(pluginConfs)
-      ? pipeline(pluginConfs.map(conf => normalize(pluginType, pluginsPath, globalOpts, conf, logger, output)))
-      : normalize(pluginType, pluginsPath, globalOpts, pluginConfs, logger, output);
+    plugins[pluginType] = pipeline(
+      castArray(pluginConfs).map(conf => normalize(pluginType, pluginsPath, globalOpts, conf, logger))
+    );
 
     return plugins;
   }, {});

package/lib/plugins/normalize.js

@@ -1,15 +1,18 @@
 const {dirname} = require('path');
-const {inspect} = require('util');
-const SemanticReleaseError = require('@semantic-release/error');
-const {isString, isObject, isFunction, noop, cloneDeep} = require('lodash');
+const {isString, isPlainObject, isFunction, noop, cloneDeep} = require('lodash');
 const resolveFrom = require('resolve-from');
+const getError = require('../get-error');
+const {extractErrors} = require('../utils');
+const PLUGINS_DEFINITIONS = require('../definitions/plugins');
 
-module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger, validator) => {
+module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger) => {
   if (!pluginOpts) {
     return noop;
   }
 
   const {path, ...config} = isString(pluginOpts) || isFunction(pluginOpts) ? {path: pluginOpts} : pluginOpts;
+  const pluginName = isFunction(path) ? `[Function: ${path.name}]` : path;
+
   if (!isFunction(pluginOpts)) {
     if (pluginsPath[path]) {
       logger.log('Load plugin %s from %s in shareable config %s', pluginType, path, pluginsPath[path]);
@@ -28,21 +31,27 @@ module.exports = (pluginType, pluginsPath, globalOpts, pluginOpts, logger, valid
   let func;
   if (isFunction(plugin)) {
     func = plugin.bind(null, cloneDeep({...globalOpts, ...config}));
-  } else if (isObject(plugin) && plugin[pluginType] && isFunction(plugin[pluginType])) {
+  } else if (isPlainObject(plugin) && plugin[pluginType] && isFunction(plugin[pluginType])) {
     func = plugin[pluginType].bind(null, cloneDeep({...globalOpts, ...config}));
   } else {
-    throw new SemanticReleaseError(
-      `The ${pluginType} plugin must be a function, or an object with a function in the property ${pluginType}.`,
-      'EPLUGINCONF'
-    );
+    throw getError('EPLUGIN', {pluginType, pluginName});
   }
 
-  return async input => {
-    const result = await func(cloneDeep(input));
-
-    if (validator && !validator.validator(result)) {
-      throw new Error(`${validator.message} Received: ${inspect(result)}`);
-    }
-    return result;
-  };
+  return Object.defineProperty(
+    async input => {
+      const definition = PLUGINS_DEFINITIONS[pluginType];
+      try {
+        const result = await func(cloneDeep(input));
+        if (definition && definition.output && !definition.output.validator(result)) {
+          throw getError(PLUGINS_DEFINITIONS[pluginType].output.error, {result, pluginName});
+        }
+        return result;
+      } catch (err) {
+        extractErrors(err).forEach(err => Object.assign(err, {pluginName}));
+        throw err;
+      }
+    },
+    'pluginName',
+    {value: pluginName, writable: false, enumerable: true}
+  );
 };

package/lib/plugins/pipeline.js

@@ -1,33 +1,55 @@
 const {identity} = require('lodash');
-const pReflect = require('p-reflect');
 const pReduce = require('p-reduce');
 const AggregateError = require('aggregate-error');
+const {extractErrors} = require('../utils');
 
-module.exports = steps => async (input, settleAll = false, getNextInput = identity) => {
+/**
+ * A Function that execute a list of function sequencially. If at least one Function ins the pipeline throw an Error or rejects, the pipeline function rejects as well.
+ *
+ * @typedef {Function} Pipeline
+ * @param {Any} input Argument to pass to the first step in the pipeline.
+ * @param {Object} options Pipeline options.
+ * @param {Boolean} [options.settleAll=false] If `true` all the steps in the pipeline are executed, even if one rejects, if `false` the execution stops after a steps rejects.
+ * @param {Function} [options.getNextInput=identity] Function called after each step is executed, with the last and current step results; the returned value will be used as the argument of the next step.
+ * @param {Function} [options.transform=identity] Function called after each step is executed, with the current step result and the step function; the returned value will be saved in the pipeline results.
+ *
+ * @return {Array<*>|*} An Array with the result of each step in the pipeline; if there is only 1 step in the pipeline, the result of this step is returned directly.
+ *
+ * @throws {AggregateError|Error} An AggregateError with the errors of each step in the pipeline that rejected; if there is only 1 step in the pipeline, the error of this step is thrown directly.
+ */
+
+/**
+ * Create a Pipeline with a list of Functions.
+ *
+ * @param {Array<Function>} steps The list of Function to execute.
+ * @return {Pipeline} A Function that execute the `steps` sequencially
+ */
+module.exports = steps => async (input, {settleAll = false, getNextInput = identity, transform = identity} = {}) => {
   const results = [];
   const errors = [];
   await pReduce(
     steps,
-    async (prevResult, nextStep) => {
+    async (lastResult, step) => {
       let result;
-
-      // Call the next step with the input computed at the end of the previous iteration and save intermediary result
-      if (settleAll) {
-        const {isFulfilled, value, reason} = await pReflect(nextStep(prevResult));
-        result = isFulfilled ? value : reason;
-        (isFulfilled ? results : errors).push(result);
-      } else {
-        result = await nextStep(prevResult);
+      try {
+        // Call the step with the input computed at the end of the previous iteration and save intermediary result
+        result = await transform(await step(lastResult), step);
         results.push(result);
+      } catch (err) {
+        if (settleAll) {
+          errors.push(...extractErrors(err));
+          result = err;
+        } else {
+          throw err;
+        }
       }
-
-      // Prepare input for next step, passing the result of the previous iteration and the current one
-      return getNextInput(prevResult, result);
+      // Prepare input for the next step, passing the result of the last iteration (or initial parameter for the first iteration) and the current one
+      return getNextInput(lastResult, result);
     },
     input
   );
   if (errors.length > 0) {
-    throw new AggregateError(errors);
+    throw errors.length === 1 ? errors[0] : new AggregateError(errors);
   }
-  return results;
+  return results.length <= 1 ? results[0] : results;
 };

package/lib/utils.js

@@ -0,0 +1,7 @@
+const {isFunction} = require('lodash');
+
+function extractErrors(err) {
+  return err && isFunction(err[Symbol.iterator]) ? [...err] : [err];
+}
+
+module.exports = {extractErrors};

package/lib/verify.js

@@ -1,44 +1,29 @@
 const {template} = require('lodash');
-const SemanticReleaseError = require('@semantic-release/error');
 const AggregateError = require('aggregate-error');
 const {isGitRepo, verifyAuth, verifyTagName} = require('./git');
+const getError = require('./get-error');
 
 module.exports = async (options, branch, logger) => {
   const errors = [];
 
   if (!await isGitRepo()) {
-    logger.error('Semantic-release must run from a git repository.');
-    return false;
-  }
-
-  if (!options.repositoryUrl) {
-    errors.push(new SemanticReleaseError('The repositoryUrl option is required', 'ENOREPOURL'));
+    errors.push(getError('ENOGITREPO'));
+  } else if (!options.repositoryUrl) {
+    errors.push(getError('ENOREPOURL'));
   } else if (!await verifyAuth(options.repositoryUrl, options.branch)) {
-    errors.push(
-      new SemanticReleaseError(
-        `The git credentials doesn't allow to push on the branch ${options.branch}.`,
-        'EGITNOPERMISSION'
-      )
-    );
+    errors.push(getError('EGITNOPERMISSION', {options}));
   }
 
   // Verify that compiling the `tagFormat` produce a valid Git tag
   if (!await verifyTagName(template(options.tagFormat)({version: '0.0.0'}))) {
-    errors.push(
-      new SemanticReleaseError('The tagFormat template must compile to a valid Git tag format', 'EINVALIDTAGFORMAT')
-    );
+    errors.push(getError('EINVALIDTAGFORMAT', {tagFormat: options.tagFormat}));
   }
 
   // Verify the `tagFormat` contains the variable `version` by compiling the `tagFormat` template
   // with a space as the `version` value and verify the result contains the space.
   // The space is used as it's an invalid tag character, so it's guaranteed to no be present in the `tagFormat`.
   if ((template(options.tagFormat)({version: ' '}).match(/ /g) || []).length !== 1) {
-    errors.push(
-      new SemanticReleaseError(
-        `The tagFormat template must contain the variable "\${version}" exactly once`,
-        'ETAGNOVERSION'
-      )
-    );
+    errors.push(getError('ETAGNOVERSION', {tagFormat: options.tagFormat}));
   }
 
   if (errors.length > 0) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "semantic-release",
   "description": "Automated semver compliant package publishing",
-  "version": "13.2.0",
+  "version": "13.4.1",
   "author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
   "bin": {
     "semantic-release": "bin/semantic-release.js"
@@ -20,9 +20,9 @@
   ],
   "dependencies": {
     "@semantic-release/commit-analyzer": "^5.0.0",
-    "@semantic-release/error": "^2.1.0",
-    "@semantic-release/github": "^4.0.2",
-    "@semantic-release/npm": "^3.0.0",
+    "@semantic-release/error": "^2.2.0",
+    "@semantic-release/github": "^4.1.0",
+    "@semantic-release/npm": "^3.1.0",
     "@semantic-release/release-notes-generator": "^6.0.0",
     "aggregate-error": "^1.0.0",
     "chalk": "^2.3.0",
@@ -40,10 +40,10 @@
     "marked-terminal": "^2.0.0",
     "p-locate": "^2.0.0",
     "p-reduce": "^1.0.0",
-    "p-reflect": "^1.0.0",
     "read-pkg-up": "^3.0.0",
     "resolve-from": "^4.0.0",
-    "semver": "^5.4.1"
+    "semver": "^5.4.1",
+    "yargs": "^11.0.0"
   },
   "devDependencies": {
     "ava": "^0.25.0",

package/lib/plugins/definitions.js

@@ -1,55 +0,0 @@
-const {isString, isFunction, isArray} = require('lodash');
-
-const RELEASE_TYPE = ['major', 'premajor', 'minor', 'preminor', 'patch', 'prepatch', 'prerelease'];
-const validatePluginConfig = conf => isString(conf) || isString(conf.path) || isFunction(conf);
-
-module.exports = {
-  verifyConditions: {
-    default: ['@semantic-release/npm', '@semantic-release/github'],
-    config: {
-      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "verifyConditions" plugin, if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-  analyzeCommits: {
-    default: '@semantic-release/commit-analyzer',
-    config: {
-      validator: conf => Boolean(conf) && validatePluginConfig(conf),
-      message:
-        'The "analyzeCommits" plugin is mandatory, and must be a single plugin definition. A plugin definition is either a string or an object with a path property.',
-    },
-    output: {
-      validator: output => !output || RELEASE_TYPE.includes(output),
-      message: 'The "analyzeCommits" plugin output, if defined, must be a valid semver release type.',
-    },
-  },
-  verifyRelease: {
-    default: false,
-    config: {
-      validator: conf => !conf || (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "verifyRelease" plugin, if defined, must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-  generateNotes: {
-    default: '@semantic-release/release-notes-generator',
-    config: {
-      validator: conf => !conf || validatePluginConfig(conf),
-      message:
-        'The "generateNotes" plugin, if defined, must be a single plugin definition. A plugin definition is either a string or an object with a path property.',
-    },
-    output: {
-      validator: output => !output || isString(output),
-      message: 'The "generateNotes" plugin output, if defined, must be a string.',
-    },
-  },
-  publish: {
-    default: ['@semantic-release/npm', '@semantic-release/github'],
-    config: {
-      validator: conf => Boolean(conf) && (isArray(conf) ? conf : [conf]).every(conf => validatePluginConfig(conf)),
-      message:
-        'The "publish" plugin is mandatory, and must be a single or an array of plugins definition. A plugin definition is either a string or an object with a path property.',
-    },
-  },
-};