semantic-release 15.13.17 → 15.13.21

package/docs/02-extending/shareable-configurations-list.md

@@ -0,0 +1,13 @@
+# Shareable configurations list
+
+## Official configurations
+- [@semantic-release/apm-config](https://github.com/semantic-release/apm-config) - semantic-release shareable configuration for releasing atom packages
+- [@semantic-release/gitlab-config](https://github.com/semantic-release/gitlab-config) - semantic-release shareable configuration for GitLab
+
+## Community configurations
+- [@jedmao/semantic-release-npm-github-config](https://github.com/jedmao/semantic-release-npm-github-config)
+  - Provides an informative [git](https://github.com/semantic-release/git) commit message for the release commit that does not trigger continuous integration and conforms to the [conventional commits specification](https://www.conventionalcommits.org/) (e.g., "chore(release): 1.2.3 [skip ci]\n\nnotes").
+  - Creates a tarball that gets uploaded with each [GitHub release](https://github.com/semantic-release/github).
+  - Publishes the same tarball to [npm](https://github.com/semantic-release/npm).
+  - Commits the version change in `package.json`.
+  - Creates or updates a [changelog](https://github.com/semantic-release/changelog) file.

package/docs/03-recipes/README.md

@@ -0,0 +1,3 @@
+# Git hosted services
+- [Git authentication with SSH keys](git-auth-ssh-keys.md)
+

package/docs/03-recipes/ci-pipelines-recipes.md

@@ -0,0 +1,4 @@
+# CI pipelines recipes
+- [CircleCI 2.0 workflows](circleci-workflows.md)
+- [Travis CI](travis.md)
+- [GitLab CI](gitlab-ci.md)

package/docs/{recipes → 03-recipes}/circleci-workflows.md

@@ -2,9 +2,9 @@
 
 ## 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)..
+The [Authentication](../01-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/getting-started.md#getting-started).
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../01-usage/getting-started.md#guided-setup-through-semantic-release-cli).
 
 ## Multiple Node jobs configuration
 
@@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
 
 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).
+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](../01-usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
 
 ```yaml
 version: 2
@@ -54,7 +54,7 @@ workflows:
 
 ### `package.json` configuration for multiple Node jobs
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../01-usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {

package/docs/{recipes → 03-recipes}/git-auth-ssh-keys.md

@@ -1,6 +1,6 @@
 # Git authentication with SSH keys
 
-When using [environment variables](../usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../usage/configuration.md#configuration) (the format will be automatically converted as needed).
+When using [environment variables](../01-usage/ci-configuration.md#authentication) to set up the Git authentication, the remote Git repository will automatically be accessed via [https](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_http_protocols), independently of the [`repositoryUrl`](../01-usage/configuration.md#repositoryurl) format configured in the **semantic-release** [Configuration](../01-usage/configuration.md#configuration) (the format will be automatically converted as needed).
 
 Alternatively the Git repository can be accessed via [SSH](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#_the_ssh_protocol) by creating SSH keys, adding the public one to your Git hosted account and making the private one available on the CI environment.
 

package/docs/03-recipes/git-hosted-services.md

@@ -0,0 +1,2 @@
+# Git hosted services
+- [Git authentication with SSH keys](git-auth-ssh-keys.md)

package/docs/{recipes → 03-recipes}/gitlab-ci.md

@@ -2,19 +2,19 @@
 
 ## Environment variables
 
-The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret variables](https://docs.gitlab.com/ce/ci/variables/README.html#secret-variables).
+The [Authentication](../01-usage/ci-configuration.md#authentication) environment variables can be configured with [Secret variables](https://docs.gitlab.com/ce/ci/variables/README.html#secret-variables).
 
 ## Node project configuration
 
 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--83).
+**Note**: The publish pipeline must run a [Node >= 8 version](../05-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 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.
+**Note**: The`semantic-release` execution command varies depending if you are using a [local](../01-usage/installation.md#local-installation) or [global](../01-usage/installation.md#global-installation) **semantic-release** installation.
 
 ```yaml
 # The release pipeline will run only if all jobs in the test pipeline are successful
@@ -46,7 +46,7 @@ publish:
 
 ### `package.json` configuration
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../01-usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {

package/docs/03-recipes/package-managers-and-languages.md

@@ -0,0 +1,2 @@
+# Package managers and languages (to be completed)
+

package/docs/{recipes → 03-recipes}/travis.md

@@ -2,9 +2,9 @@
 
 ## 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).
+The [Authentication](../01-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/getting-started.md#getting-started).
+Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../01-usage/01-getting-started.md#getting-started).
 
 ## Node.js projects configuration
 
@@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
 
 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).
+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](../01-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.
 
@@ -43,7 +43,7 @@ jobs:
 
 ### `package.json` configuration for multiple Node jobs
 
-A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
+A `package.json` is required only for [local](../01-usage/installation.md#local-installation) **semantic-release** installation.
 
 ```json
 {
@@ -57,13 +57,13 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins
 
 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.
+This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../05-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).
+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](../01-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.
 

package/docs/{developer-guide → 04-developer-guide}/js-api.md

@@ -65,9 +65,9 @@ Type: `Object`
 
 **semantic-release** options.
 
-Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration).
+Can be used to set any [core option](../01-usage/configuration.md#configuration) or [plugin options](../01-usage/plugins.md#configuration).
 
-Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends).
+Each option, will take precedence over options configured in the [configuration file](../01-usage/configuration.md#configuration) and [shareable configurations](../01-usage/configuration.md#extends).
 
 #### config
 
@@ -229,7 +229,7 @@ Example:
 
 Type: `Array<Object>`
 
-The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).<br>
+The list of releases published, one release per [publish plugin](../01-usage/plugins.md#publish-plugin).<br>
 Each release object has the following properties:
 
 | Name       | Type     | Description                                                                                   |

package/docs/04-developer-guide/plugin.md

@@ -0,0 +1,106 @@
+# Plugin Developer Guide
+
+To create a plugin for `semantic-release`, you need to decide which parts of the release lifecycle are important to that plugin. For example, it is best to always have a `verify` step because you may be receiving inputs from a user and want to make sure they exist. A plugin can abide by any of the following lifecycles:
+
+- `verify`
+- `prepare`
+- `publish`
+- `success`
+- `fail`
+
+`semantic-release` will require the plugin via `node` and look through the required object for methods named like the lifecyles stated above. For example, if your plugin only had a `verify` and `success` step, the `main` file for your object would need to `export` an object with `verify` and `success` functions.
+
+In addition to the lifecycle methods, each lifecyle is passed two objects:
+
+1. `pluginConfig` - an object containing the options that a user may pass in via their `release.config.js` file (or similar)
+2. `context` - provided by `semantic-release` for access to things like `env` variables set on the running process.
+
+For each lifecycle you create, you will want to ensure it can accept `pluginConfig` and `context` as parameters.
+
+## Creating a Plugin Project
+
+It is recommended that you generate a new project with `yarn init`. This will provide you with a basic node project to get started with. From there, create an `index.js` file, and make sure it is specified as the `main` in the `package.json`. We will use this file to orchestrate the lifecycle methods later on.
+
+Next, create a `src` or `lib` folder in the root of the project. This is where we will store our logic and code for how our lifecycle methods work. Finally, create a `test` folder so you can write tests related to your logic.
+
+We recommend you setup a linting system to ensure good javascript practices are enforced. ESLint is usually the system of choice, and the configuration can be whatever you or your team fancies.
+
+## Exposing Lifecycle Methods
+
+In your `index.js` file, you can start by writing the following code
+
+```javascript
+const verifyConditions = require('./src/verify');
+
+let verified;
+
+/**
+ * Called by semantic-release during the verification step
+ * @param {*} pluginConfig The semantic-release plugin config
+ * @param {*} context The context provided by semantic-release
+ */
+async function verify(pluginConfig, context) {
+  await verifyConditions(pluginConfig, context);
+  verified = true;
+}
+
+module.exports = { verify };
+```
+
+Then, in your `src` folder, create a file called `verify.js` and add the following
+
+```javascript
+const AggregateError = require('aggregate-error');
+
+/**
+ * A method to verify that the user has given us a slack webhook url to post to
+ */
+module.exports = async (pluginConfig, context) => {
+  const { logger } = context;
+  const errors = [];
+
+  // Throw any errors we accumulated during the validation
+  if (errors.length > 0) {
+    throw new AggregateError(errors);
+  }
+};
+```
+
+As of right now, this code won't do anything. However, if you were to run this plugin via `semantic-release`, it would run when the `verify` step occurred.
+
+Following this structure, you can create different steps and checks to run through out the release process.
+
+## Supporting Options
+
+Let's say we want to verify that an `option` is passed. An `option` is a configuration object that is specific to your plugin. For example, the user may set an `option` in their release config like:
+
+```js
+{
+    prepare: {
+        path: "@semantic-release/my-special-plugin"
+        message: "My cool release message"
+    }
+}
+```
+
+This `message` option will be passed to the `pluginConfig` object mentioned earlier. We can use the validation method we created to verify this option exists so we can perform logic based on that knowledge. In our `verify` file, we can add the following:
+
+```js
+const { message } = pluginConfig;
+
+if (message.length) {
+    //...
+}
+```
+
+## Supporting Environment Variables
+
+Similar to `options`, environment variables exist to allow users to pass tokens and set special URLs. These are set on the `context` object instead of the `pluginConfig` object. Let's say we wanted to check for `GITHUB_TOKEN` in the environment because we want to post to GitHub on the user's behalf. To do this, we can add the following to our `verify` command:
+
+```js
+const { env } = context;
+
+if (env.GITHUB_TOKEN) {
+    //...
+}
+```

package/docs/{support → 05-support}/FAQ.md

@@ -34,11 +34,11 @@ If using npm hook scripts is not possible, and alternative solution is to [`@sem
 
 ## Is there a way to preview which version would currently get published?
 
-Yes with the [dry-run options](../usage/configuration.md#dryrun) which prints to the console the next version to be published and the release notes.
+Yes with the [dry-run options](../01-usage/configuration.md#dryrun) which prints to the console the next version to be published and the release notes.
 
 ## Can I use semantic-release with Yarn?
 
-If you are using a [local](../usage/installation.md#local-installation) **semantic-release** installation and run multiple CI jobs with different versions, the `yarn install` command will fail on jobs running with Node < 8 as **semantic-release** requires [Node >= 8.3](#why-does-semantic-release-require-node-version--83) and specifies it in its `package.json`s [`engines`](https://docs.npmjs.com/files/package.json#engines) key.
+If you are using a [local](../01-usage/installation.md#local-installation) **semantic-release** installation and run multiple CI jobs with different versions, the `yarn install` command will fail on jobs running with Node < 8 as **semantic-release** requires [Node >= 8.3](#why-does-semantic-release-require-node-version--83) and specifies it in its `package.json`s [`engines`](https://docs.npmjs.com/files/package.json#engines) key.
 
 The recommended solution is to use the [Yarn](https://yarnpkg.com) [--ignore-engines](https://yarnpkg.com/en/docs/cli/install#toc-yarn-install-ignore-engines) option to install the project dependencies on the CI environment, so Yarn will ignore the **semantic-release**'s `engines` key:
 
@@ -48,7 +48,7 @@ $ yarn install --ignore-engines
 
 **Note**: Several CI services use Yarn by default if your repository contains a `yarn.lock` file. So you should override the install step to specify `yarn install --ignore-engines`.
 
-Alternatively you can use a [global](../usage/installation.md#global-installation) **semantic-release** installation and make sure to install and run the `semantic-release` command only in a CI jobs running with Node >= 8.3.
+Alternatively you can use a [global](../01-usage/installation.md#global-installation) **semantic-release** installation and make sure to install and run the `semantic-release` command only in a CI jobs running with Node >= 8.3.
 
 If your CI environment provides [nvm](https://github.com/creationix/nvm) you can switch to Node 8 before installing and running the `semantic-release` command:
 
@@ -56,14 +56,14 @@ If your CI environment provides [nvm](https://github.com/creationix/nvm) you can
 $ nvm install 8 && yarn global add semantic-release && semantic-release
 ```
 
-See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
+See the [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments.
 
 As `semantic-release` is recommended to be executed with [`npx`](https://www.npmjs.com/package/npx) an alternative is required for usage with Yarn. Even though it is possible to install npx with Yarn, it's not recommended. Yarn and npx would be using different cache locations.
 
-For [local installation](../usage/installation.md#local-installation) replace
+For [local installation](../01-usage/installation.md#local-installation) replace
 `npx semantic-release` with `yarn run semantic-release`.
 
-For [global installation](../usage/installation.md#global-installation) replace
+For [global installation](../01-usage/installation.md#global-installation) replace
 `npx semantic-release` with `yarn global add semantic-release && semantic-release`.
 
 ## Can I use semantic-release to publish non-JavaScript packages?
@@ -71,13 +71,13 @@ For [global installation](../usage/installation.md#global-installation) replace
 Yes, **semantic-release** is a Node CLI application but it can be used to publish any type of packages.
 
 To publish a non-Node package (without a `package.json`) you would need to:
-- Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
-- Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or rc file](../usage/configuration.md#configuration)
+- Use a [global](../01-usage/installation.md#global-installation) **semantic-release** installation
+- Set **semantic-release** [options](../01-usage/configuration.md#options) via [CLI arguments or rc file](../01-usage/configuration.md#configuration)
 - Make sure your CI job executing the `semantic-release` command has access to [Node >= 8](#why-does-semantic-release-require-node-version--83) to execute the `semantic-release` command
 
-See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
+See the [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments.
 
-In addition you will need to configure the **semantic-release** [plugins](../usage/plugins.md#plugins) to disable the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin which is used by default and use a plugin for your project type.
+In addition you will need to configure the **semantic-release** [plugins](../01-usage/plugins.md#plugins) to disable the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin which is used by default and use a plugin for your project type.
 
 If there is no specific plugin for your project type you can use the [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin to publish the release with a shell command.
 
@@ -99,19 +99,19 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti
 
 **Note**: This is a theoretical example where the command `set-version` update the project version with the value passed as its first argument and `publish-package` publishes the package to a registry.
 
-See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types.
+See the [package managers and languages recipes](../03-recipes/README.md#package-managers-and-languages) for more details on specific project types.
 
 ## Can I use semantic-release with any CI service?
 
 Yes, **semantic-release** can be used with any CI service, as long as it provides:
-- A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
-- A way to guarantee that the `semantic-release` command is [executed only after all the tests of all the jobs in the CI build pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
+- A way to set [authentication](../01-usage/ci-configuration.md#authentication) via environment variables
+- A way to guarantee that the `semantic-release` command is [executed only after all the tests of all the jobs in the CI build pass](../01-usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
 
-See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
+See the [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments.
 
 ## Can I run semantic-release on my local machine rather than on a CI server?
 
-Yes, you can by explicitly setting the [`--no-ci` CLI option](../usage/configuration.md#ci) option. You will also have to set the required [authentication](../usage/ci-configuration.md#authentication) via environment variables on your local machine, for example:
+Yes, you can by explicitly setting the [`--no-ci` CLI option](../01-usage/configuration.md#ci) option. You will also have to set the required [authentication](../01-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> npx semantic-release --no-ci
@@ -123,11 +123,11 @@ However this is not the recommended approach, as running unit and integration te
 
 Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
 
-See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
+See the [GitLab CI recipes](../03-recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
 
 ## Can I use semantic-release with any Git hosted environment?
 
-By default **semantic-release** uses the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin to publish a [GitHub release](https://help.github.com/articles/about-releases). For other Git hosted environment the  [`@semantic-release/git`](https://github.com/semantic-release/git) and [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) plugins can be used via [plugins configuration](../usage/plugins.md).
+By default **semantic-release** uses the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin to publish a [GitHub release](https://help.github.com/articles/about-releases). For other Git hosted environment the  [`@semantic-release/git`](https://github.com/semantic-release/git) and [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) plugins can be used via [plugins configuration](../01-usage/plugins.md).
 
 See the [`@semantic-release/git`](https://github.com/semantic-release/git#semantic-releasegit) [`@semantic-release/changelog`](https://github.com/semantic-release/changelog#semantic-releasechangelog) plugins documentation for more details.
 
@@ -230,13 +230,13 @@ See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/i
 
 **semantic-release** has a full unit and integration test suite that tests `npm` publishes against the [npm-registry-couchapp](https://github.com/npm/npm-registry-couchapp).
 
-In addition the [verify conditions step](../../README.md#release-steps) verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed [only if all your tests pass](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
+In addition the [verify conditions step](../../README.md#release-steps) verifies that all necessary conditions for proceeding with a release are met, and a new release will be performed [only if all your tests pass](../01-usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
 
 ## Why does semantic-release require Node version >= 8.3?
 
 **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.
+See [Node version requirement](/node-version.md#node-version-requirement) for more details and solutions.
 
 ## What is npx?
 

package/docs/{support → 05-support}/node-version.md

@@ -12,7 +12,7 @@ See our [Node Support Policy](node-support-policy.md) for our long-term promise
 
 The recommended approach is to run the `semantic-release` command from a CI job running on Node 8.3 or higher. This can either be a job used by your project to test on Node >= 8.3 or a dedicated job for the release steps.
 
-See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
+See [CI configuration](../01-usage/ci-configuration.md) and [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details.
 
 ## Alternative solutions
 

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
-- [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
-- [Support](support/README.md) - FAQ and troubleshooting
+- [Usage](01-usage/README.md) - **semantic-release** installation and configuration
+- [Extending](02-extending/README.md)- Extending **semantic-release** with plugins and shareable configurations
+- [Recipes](03-recipes/README.md) - Community written recipes for common **semantic-release** use-cases
+- [Developer Guide](04-developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
+- [Support](05-support/README.md) - FAQ and troubleshooting

package/lib/git.js

@@ -45,7 +45,7 @@ async function isRefInHistory(ref, execaOpts) {
     await execa('git', ['merge-base', '--is-ancestor', ref, 'HEAD'], execaOpts);
     return true;
   } catch (error) {
-    if (error.exitCode === 1) {
+    if (error.code === 1) {
       return false;
     }
 
@@ -103,7 +103,7 @@ async function repoUrl(execaOpts) {
  */
 async function isGitRepo(execaOpts) {
   try {
-    return (await execa('git', ['rev-parse', '--git-dir'], execaOpts)).exitCode === 0;
+    return (await execa('git', ['rev-parse', '--git-dir'], execaOpts)).code === 0;
   } catch (error) {
     debug(error);
   }
@@ -161,7 +161,7 @@ async function push(repositoryUrl, execaOpts) {
  */
 async function verifyTagName(tagName, execaOpts) {
   try {
-    return (await execa('git', ['check-ref-format', `refs/tags/${tagName}`], execaOpts)).exitCode === 0;
+    return (await execa('git', ['check-ref-format', `refs/tags/${tagName}`], execaOpts)).code === 0;
   } catch (error) {
     debug(error);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "semantic-release",
   "description": "Automated semver compliant package publishing",
-  "version": "15.13.17",
+  "version": "15.13.21",
   "author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
   "ava": {
     "files": [
@@ -17,11 +17,6 @@
   "bugs": {
     "url": "https://github.com/semantic-release/semantic-release/issues"
   },
-  "config": {
-    "commitizen": {
-      "path": "cz-conventional-changelog"
-    }
-  },
   "contributors": [
     "Gregor Martynus (https://twitter.com/gr2m)",
     "Pierre Vanduynslager (https://twitter.com/@pvdlg_)"
@@ -36,15 +31,15 @@
     "cosmiconfig": "^5.0.1",
     "debug": "^4.0.0",
     "env-ci": "^4.0.0",
-    "execa": "^2.0.0",
+    "execa": "^1.0.0",
     "figures": "^3.0.0",
     "find-versions": "^3.0.0",
     "get-stream": "^5.0.0",
     "git-log-parser": "^1.2.0",
     "hook-std": "^2.0.0",
-    "hosted-git-info": "^2.7.1",
-    "lodash": "^4.17.4",
-    "marked": "^0.6.0",
+    "hosted-git-info": "^3.0.0",
+    "lodash": "^4.17.15",
+    "marked": "^0.7.0",
     "marked-terminal": "^3.2.0",
     "p-locate": "^4.0.0",
     "p-reduce": "^2.0.0",
@@ -56,10 +51,8 @@
   },
   "devDependencies": {
     "ava": "^2.0.0",
-    "clear-module": "^3.0.0",
+    "clear-module": "^4.0.0",
     "codecov": "^3.0.0",
-    "commitizen": "^3.0.0",
-    "cz-conventional-changelog": "^2.0.0",
     "delay": "^4.0.0",
     "dockerode": "^2.5.2",
     "file-url": "^3.0.0",
@@ -125,7 +118,6 @@
     "url": "git+https://github.com/semantic-release/semantic-release.git"
   },
   "scripts": {
-    "cm": "git-cz",
     "codecov": "codecov -f coverage/coverage-final.json",
     "lint": "xo",
     "pretest": "npm run lint",

package/docs/developer-guide/plugin.md

@@ -1 +0,0 @@
-# Plugin developer guide

package/docs/extending/shareable-configurations-list.md

@@ -1,7 +0,0 @@
-# Shareable configurations list
-
-## Official configurations
-- [@semantic-release/apm-config](https://github.com/semantic-release/apm-config) - semantic-release shareable configuration for releasing atom packages
-- [@semantic-release/gitlab-config](https://github.com/semantic-release/gitlab-config) - semantic-release shareable configuration for GitLab
-
-## Community configurations

package/docs/recipes/README.md

@@ -1,11 +0,0 @@
-# Recipes
-
-## CI configurations
-- [CircleCI 2.0 workflows](circleci-workflows.md)
-- [Travis CI](travis.md)
-- [GitLab CI](gitlab-ci.md)
-
-## Git hosted services
-- [Git authentication with SSH keys](git-auth-ssh-keys.md)
-
-## Package managers and languages

package/docs/usage/getting-started.md

@@ -1,22 +0,0 @@
-# Getting started
-
-In order to use **semantic-release** you must follow these steps:
-- [Install](./installation.md#installation) **semantic-release** in your project
-- Configure your Continuous Integration service to [run **semantic-release**](./ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
-- Configure your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
-- Configure **semantic-release** [options and plugins](./configuration.md#configuration)
-
-Alternatively those steps can be easily done with the [**semantic-release** interactive CLI](https://github.com/semantic-release/cli):
-
-```bash
-npm install -g semantic-release-cli
-
-cd your-module
-semantic-release-cli setup
-```
-
-![dialogue](../../media/semantic-release-cli.png)
-
-See the [semantic-release-cli](https://github.com/semantic-release/cli#what-it-does) documentation for more details.
-
-**Note**: only a limited number of options, CI services and plugins are currently supported by `semantic-release-cli`.

package/docs/usage/installation.md

@@ -1,29 +0,0 @@
-# Installation
-
-## Local installation
-
-For [Node modules projects](https://docs.npmjs.com/getting-started/creating-node-modules) we recommend installing **semantic-release** locally and running the `semantic-release` command with [npx](https://www.npmjs.com/package/npx):
-
-```bash
-$ npm install --save-dev semantic-release
-```
-
-Then in the CI environment:
-
-```bash
-$ 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 installing **semantic-release** directly in the CI environment, also with [npx](https://www.npmjs.com/package/npx):
-
-```bash
-$ npx semantic-release
-```
-
-**Note:** For a global installation, it's recommended to specify the major **semantic-release** version to install (for example with with `npx semantic-release@15`, or `npm install -g semantic-release@15`). 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.

package/docs/usage/shareable-configurations.md

@@ -1,7 +0,0 @@
-# Shareable configurations
-
-A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects.
-
-The shareable configurations to use can be set with the [extends](configuration.md#extends) option.
-
-See [shareable configurations list](../extending/shareable-configurations-list.md).