semantic-release 15.13.17 → 15.13.21

package/README.md

@@ -39,10 +39,10 @@ This removes the immediate connection between human emotions and version numbers
 - 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)
+- Integrate with your [continuous integration workflow](docs/03-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)
-- Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
+- Support any [package managers and languages](docs/03-recipes/README.md#package-managers-and-languages) via [plugins](docs/01-usage/plugins.md)
+- Simple and reusable configuration via [shareable configurations](docs/01-usage/shareable-configurations.md)
 
 ## How does it work?
 
@@ -50,7 +50,7 @@ This removes the immediate connection between human emotions and version numbers
 
 **semantic-release** uses the commit messages to determine the type of changes in the codebase. Following formalized conventions for commit messages, **semantic-release** automatically determines the next [semantic version](https://semver.org) number, generates a changelog and publishes the release.
 
-By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). The commit message format can be changed with the [`preset` or `config` options](docs/usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.
+By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). The commit message format can be changed with the [`preset` or `config` options](docs/01-usage/configuration.md#options) of the [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#options) and [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator#options) plugins.
 
 Tools such as [commitizen](https://github.com/commitizen/cz-cli), [commitlint](https://github.com/conventional-changelog/commitlint) or [semantic-git-commit-cli](https://github.com/JPeer264/node-semantic-git-commit-cli) can be used to help contributors and enforce valid commit messages.
 
@@ -71,50 +71,55 @@ Here is an example of the release type that will be done based on a commit messa
 For each new commits added 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 codebase changes since the last release that affect the package functionalities.
 
 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.
+- 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. **NOTE**: `16.0.0-beta` of semantic-release, includes new features to automate the release of different branches to different npm distribution tags. The corresponding documentation can be found [on the beta branch of this repo](https://github.com/semantic-release/semantic-release/blob/beta/docs/recipes/distribution-channels.md#publishing-on-distribution-channels).
 - Develop on a `dev` branch and merge it to the release branch (i.e. `master`) once you are ready to publish. **semantic-release** will run only on pushes to the release branch.
 
 ### Release steps
 
 After running the tests, the command `semantic-release` will execute the following steps:
 
-| Step              | Description                                                                                                                     |
-|-------------------|---------------------------------------------------------------------------------------------------------------------------------|
-| Verify Conditions | Verify all the conditions to proceed with the release.                                                                          |
-| Get last release  | Obtain the commit corresponding to the last release by analyzing [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
-| Analyze commits   | Determine the type of release based on the commits added since the last release.                                                |
-| Verify release    | Verify the release conformity.                                                                                                  |
-| Generate notes    | Generate release notes for the commits added since the last release.                                                            |
-| Create Git tag    | Create a Git tag corresponding to the new release version.                                                                      |
-| Prepare           | Prepare the release.                                                                                                            |
-| Publish           | Publish the release.                                                                                                            |
-| Notify            | Notify of new releases or errors.                                                                                               |
+| Step              | Step Hook            | Description                                                                                                                     |
+|-------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------|
+| Verify Conditions | `verifyConditions`   | Verify all the conditions to proceed with the release.                                                                          |
+| Get last release  | N/A                  | Obtain the commit corresponding to the last release by analyzing [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). |
+| Analyze commits   | N/A                  | Determine the type of release based on the commits added since the last release.                                                |
+| Verify release    | `verifyRelease`      | Verify the release conformity.                                                                                                  |
+| Generate notes    | `generateNotes`      | Generate release notes for the commits added since the last release.                                                            |
+| Create Git tag    | N/A                  | Create a Git tag corresponding to the new release version.                                                                      |
+| Prepare           | `prepare`            | Prepare the release.                                                                                                            |
+| Publish           | `publish`            | Publish the release.                                                                                                            |
+| Notify            | `success`, `failure` | Notify of new releases or errors.                                                                                               |
 
 ## Documentation
 
 - Usage
-  - [Getting started](docs/usage/getting-started.md#getting-started)
-  - [Installation](docs/usage/installation.md#installation)
-  - [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
-  - [Configuration](docs/usage/configuration.md#configuration)
-  - [Plugins](docs/usage/plugins.md)
-  - [Shareable configurations](docs/usage/shareable-configurations.md)
+  - [Getting started](docs/01-usage/getting-started.md)
+  - [Installation](docs/01-usage/installation.md#installation)
+  - [CI Configuration](docs/01-usage/ci-configuration.md#ci-configuration)
+  - [Configuration](docs/01-usage/configuration.md#configuration)
+  - [Plugins](docs/01-usage/plugins.md)
+  - [Shareable configurations](docs/01-usage/shareable-configurations.md)
 - Extending
-  - [Plugins](docs/extending/plugins-list.md)
-  - [Shareable configuration](docs/extending/shareable-configurations-list.md)
+  - [Available plugins](docs/02-extending/plugins-list.md)
+  - [Available shareable configuration](docs/02-extending/shareable-configurations-list.md)
 - Recipes
-  - [CI configurations](docs/recipes/README.md)
-  - [Package managers and languages](docs/recipes/README.md)
+  - [CI pipelines recipes](docs/03-recipes/ci-pipelines-recipes.md)
+    - [CircleCI 2.0 workflows](docs/03-recipes/circleci-workflows.md)
+    - [Travis CI](docs/03-recipes/travis.md)
+    - [GitLab CI](docs/03-recipes/gitlab-ci.md)
+  - [Git hosted services](docs/03-recipes/git-hosted-services.md)
+    - [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
+  - [Package managers and languages](docs/03-recipes/package-managers-and-languages.md)
 - Developer guide
-  - [JavaScript API](docs/developer-guide/js-api.md)
-  - [Plugins](docs/developer-guide/plugin.md)
-  - [Shareable configuration](docs/developer-guide/shareable-configuration.md)
+  - [JavaScript API](docs/04-developer-guide/js-api.md)
+  - [Plugin development](docs/04-developer-guide/plugin.md)
+  - [Shareable configuration development](docs/04-developer-guide/shareable-configuration.md)
 - Support
-  - [Resources](docs/support/resources.md)
-  - [Frequently Asked Questions](docs/support/FAQ.md)
-  - [Troubleshooting](docs/support/troubleshooting.md)
-  - [Node version requirement](docs/support/node-version.md)
-  - [Node Support Policy](docs/support/node-support-policy.md)
+  - [Resources](docs/05-support/resources.md)
+  - [Frequently Asked Questions](docs/05-support/FAQ.md)
+  - [Troubleshooting](docs/05-support/troubleshooting.md)
+  - [Node version requirement](docs/05-support/node-version.md)
+  - [Node Support Policy](docs/05-support/node-support-policy.md)
 
 ## Get help
 

package/docs/{usage → 01-usage}/ci-configuration.md

@@ -1,14 +1,29 @@
 # CI configuration
 
-## Run `semantic-release` only after all tests succeeded
+## Running `semantic-release`
 
-The `semantic-release` command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the `semantic-release` command is executed only after all jobs are successful. This can be achieved with [Travis Build Stages](https://docs.travis-ci.com/user/build-stages), [CircleCI Workflows](https://circleci.com/docs/2.0/workflows), [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines), [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html#introduction-to-pipelines-and-jobs), [Codefresh Pipelines](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines), [Wercker Workflows](http://devcenter.wercker.com/docs/workflows) or [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).
+The `semantic-release` command will only run fully in a CI environment. If it does not detect that it is in a CI environment, it will automatically run in `dry-run` mode.
+ 
+Within a CI environment, the `semantic-release` command must be executed only after all the tests in the CI build pass, otherwise it will release potentially faulty code. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the `semantic-release` command is executed only after all jobs are successful. 
 
-See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
+Follow the CI system's documentation to find out how to do this:
+- [Travis Build Stages](https://docs.travis-ci.com/user/build-stages)
+- [CircleCI Workflows](https://circleci.com/docs/2.0/workflows)
+- [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines)
+- [GitLab Pipelines](https://docs.gitlab.com/ee/ci/pipelines.html#introduction-to-pipelines-and-jobs)
+- [Codefresh Pipelines](https://codefresh.io/docs/docs/configure-ci-cd-pipeline/introduction-to-codefresh-pipelines)
+- [Wercker Workflows](http://devcenter.wercker.com/docs/workflows)
+- [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).
+
+This documentation provides a few [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details.
 
 ## Authentication
 
-**semantic-release** requires push access to the project Git repository in order to create [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). The Git authentication can be set with one of the following environment variables:
+### Push access to remote repos
+
+**semantic-release** requires push access to remote Git repositories in order to push the [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) it created.
+
+The Git authentication can be set with one of the following environment variables:
 
 | Variable                        | Description                                                                                                                                                                                                                  |
 |---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -17,17 +32,22 @@ See [CI configuration recipes](../recipes/README.md#ci-configurations) for more
 | `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html).                                                                                                 |
 | `GIT_CREDENTIALS`               | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `<username>:<password>`. The username and password must each be individually URL encoded, not the `:` separating them. |
 
-Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-auth-ssh-keys.md).
+Alternatively the Git authentication **can be set up via [SSH keys](../03-recipes/git-auth-ssh-keys.md)**.
 
-Most **semantic-release** [plugins](plugins.md) require setting up authentication in order to publish to a package manager registry. The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) and [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugins require the following environment variables:
+### Authentication needs for plugins
+
+Most **semantic-release** [plugins](plugins.md) require setting up authentication in order to publish to a package manager registry. See each plugin's documentation for the environment variables required.
+
+It is to note, however, that:
+- The default [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugin requires the same `GH_TOKEN` environment variable as above
+- The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) plugin requires the following environment variables:
 
 | Variable    | Description                                                                                                                                                                                                                                                                                                               |
 |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `NPM_TOKEN` | npm token created via [npm token create](https://docs.npmjs.com/getting-started/working_with_tokens#how-to-create-new-tokens).<br/>**Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported. |
-| `GH_TOKEN`  | GitHub authentication token.<br/>**Note**: Only the [personal token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) authentication is supported.                                                                                                                                 |
 
 See each plugin's documentation for the environment variables required.
 
-The authentication token/credentials have to be made available in the CI service via environment variables.
-
-See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
+> **Note**: The authentication token/credentials have to be made available in the CI service via environment variables.
+>
+> See [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on how to configure environment variables in your CI service.

package/docs/{usage → 01-usage}/configuration.md

@@ -1,73 +1,93 @@
 # Configuration
 
 **semantic-release** configuration consists of:
-- Git repository options ([URL](#repositoryurl), [release branch](#branch) and [tag format](#tagformat))
-- [plugins](#plugins) definition
-- run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
+- Git repository [url](#repositoryurl) and options ([release branch](#branch) and [tag format](#tagformat)). ([Access credentials](ci-configuration.md) are setup through environment variables)
+- Plugins [declaration](#plugins) and [options](plugins.md).
+- Run mode ([`--dry-run`](#dryrun), [`--no-ci`](#ci) (local), [`--debug`](#debug)).
 
-All of these options can be configured directly or by extending a [shareable configuration](shareable-configurations.md).
+All of these options can be configured:
+- In a config file.
+- Through the cli.
+- By extending a [shareable configuration](shareable-configurations.md).
 
 Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables).
 
-## Configuration file
+## Configuring/passing options to `semantic-release`
 
-**semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via:
-- A `.releaserc` file, written in YAML or JSON, with optional extensions: .`yaml`/`.yml`/`.json`/`.js`
-- A `release.config.js` file that exports an object
-- A `release` key in the project's `package.json` file
+### Configuration file
 
-Alternatively, some options can be set via CLI arguments.
+> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.
 
-The following three examples are the same.
+**semantic-release**’s options, mode and plugins can be set via a config file in different ways:
+- A `.releaserc` file, written in YAML or JSON, with optional extensions `.yaml`, `.yml`, `.json` or `.js`.
+- A `release.config.js` file that exports an object.
+- A `release` key in the project's `package.json` file.
 
-Via `release` key in the project's `package.json` file:
+The following two examples are the same:
+- Via `.releaserc` or `release.config.js` file:    
+    ```json
+    {
+      "branch": "next"
+    }
+    ```
+- Via `release` key in the project's `package.json` file (the configuration must be under the `release` property):
+    ```json
+    {
+      "release": {
+        "branch": "next"
+      }
+    }
+    ```
 
-```json
-{
-  "release": {
-    "branch": "next"
-  }
-}
-```
-```bash
-$ semantic-release
-```
+### Using CLI arguments
 
-Via `.releaserc` file:
+> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.
 
-```json
-{
-  "branch": "next"
-}
-```
-```bash
-$ semantic-release
-```
+Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
 
-Via CLI argument:
+The following configuration example via CLI argument is equivalent to the configuration file's example:
 
 ```bash
 $ semantic-release --branch next
 ```
 
-**Note**: CLI arguments take precedence over options configured in the configuration file.
+### Extending a shareable configuration
 
-**Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
+> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.
 
-**Note**: When configuring via `package.json`, the configuration must be under the `release` property. However, when using a `.releaserc` or a `release.config.js` file, the configuration must be set without a `release` property.
+Please see [shareable configuration](shareable-configurations.md) for more details.
 
 ## Options
 
-### extends
+### `extends`
 
 Type: `Array`, `String`<br>
 CLI arguments: `-e`, `--extends`
 
-List of modules or file paths containing a [shareable configuration](shareable-configurations.md). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration.
-
-**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
-
-### branch
+Contains a list of:
+- Modules.
+- File paths containing a [shareable configuration](shareable-configurations.md). 
+
+> **Note**:  If multiple shareable configurations are set, they will be imported **in the order defined with each configuration option** taking precedence over the options defined in a previous shareable configuration.
+
+Examples (`.releaserc` file content):
+- `Array`:
+    ```json
+    {
+      "extends": [
+        "./my_config_dir/my.config",
+        "@semantic-release/gitlab-config",
+      ]
+    }
+    ```
+- `String`:
+    ```json
+    {
+      "extends": "@semantic-release/gitlab-config"
+    }
+    ```
+
+### `branch`
 
 Type: `String`<br>
 Default: `master`<br>
@@ -75,7 +95,14 @@ CLI arguments: `-b`, `--branch`
 
 The branch on which releases should happen.
 
-### repositoryUrl
+Example (`.releaserc` file content):
+```json
+{
+  "branch": "next"
+}
+```
+
+### `repositoryUrl`
 
 Type: `String`<br>
 Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)<br>
@@ -85,7 +112,14 @@ 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)).
 
-### tagFormat
+Example (`.releaserc` file content):
+```json
+{
+  "repositoryUrl": "https://github.com/username/project.git"
+}
+```
+
+### `tagFormat`
 
 Type: `String`<br>
 Default: `v${version}`<br>
@@ -93,21 +127,41 @@ 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 exactly once 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).
 
-### plugins
+Example (`.releaserc` file content):
+```json
+{
+  "tagFormat": "version-${version}"
+}
+```
+
+### `plugins`
 
 Type: `Array`<br>
 Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`<br>
 CLI arguments: `-p`, `--plugins`
 
-Define the list of plugins to use. Plugins will run in series, in the order defined, for each [steps](../../README.md#release-steps) if they implement it.
-
-Plugins configuration can defined by wrapping the name and an options object in an array.
+Define the list of plugins to use. Plugins will run in series, **in the order defined**, for **each [steps](../../README.md#release-steps)** if they implement it.
 
-See [Plugins configuration](plugins.md#plugins) for more details.
+Plugin specific configuration can defined by wrapping the name and an options object in an array. See [Plugins configuration options](plugins.md#plugins-configuration-options) for more details.
 
-### dryRun
+Example (`.releaserc` file content):
+```json
+{
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release-docker",
+    ["@semantic-release/exec", {
+      "verifyConditionsCmd": "./verify.sh"
+    }],
+    "@semantic-release/git",
+    "@semantic-release/gitlab",
+  ]
+}
+```
+### `dryRun`
 
 Type: `Boolean`<br>
 Default: `false` if running in a CI environment, `true` otherwise<br>
@@ -115,7 +169,14 @@ CLI arguments: `-d`, `--dry-run`
 
 Dry-run mode, skip publishing, print next version and release notes.
 
-### ci
+Example (`.releaserc` file content):
+```json
+{
+  "dryRun": "true"
+}
+```
+
+### `ci`
 
 Type: `Boolean`<br>
 Default: `true`<br>
@@ -123,9 +184,16 @@ CLI arguments: `--ci` / `--no-ci`
 
 Set to `false` to skip Continuous Integration environment verifications. This allows for making releases from a local machine.
 
-**Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`.
+> **Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`.
+
+Example (`.releaserc` file content):
+```json
+{
+  "ci": "false"
+}
+```
 
-### debug
+### `debug` (only through CLI)
 
 Type: `Boolean`<br>
 Default: `false`<br>
@@ -133,7 +201,12 @@ CLI argument: `--debug`
 
 Output debugging information. This can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.
 
-**Note**: The `debug` is used only supported via CLI argument. To enable debug mode from the [JS API](../developer-guide/js-api.md#javascript-api) use `require('debug').enable('semantic-release:*')`.
+> **Note**: The `debug` is used only supported via CLI argument. To enable debug mode from the [JS API](../04-developer-guide/js-api.md#javascript-api) use `require('debug').enable('semantic-release:*')`.
+
+Example:
+```bash
+$ semantic-release --debug
+```
 
 ## Git environment variables
 
@@ -144,9 +217,11 @@ Output debugging information. This can also be enabled by setting the `DEBUG` en
 | `GIT_COMMITTER_NAME`  | The committer name associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing).  | @semantic-release-bot.               |
 | `GIT_COMMITTER_EMAIL` | The committer email associated with the [Git release tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging). See [Git environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_committing). | @semantic-release-bot email address. |
 
-## Existing version tags
+## Existing version tags, and how semantic-release deals with them
+
+**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. 
 
-**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release. If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branch](#branch) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).
+If a release has been published before setting up **semantic-release** you must make sure the most recent commit included in the last published release is in the [release branch](#branch) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).
 
 If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.
 

package/docs/01-usage/getting-started.md

@@ -0,0 +1,32 @@
+# Getting started
+
+## Manual setup
+
+You can use **semantic-release** with the following manual setup steps:
+
+1. [Install **semantic-release**](installation.md) either locally for your project or globally
+1. Configure:
+    1. Your Continuous Integration service to [run **semantic-release**](ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
+    1. Your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
+    1. **semantic-release**'s [options and plugins](configuration.md)
+
+## Guided setup through `semantic-release-cli`
+Alternatively you can be guided through those setup steps thanks to the [interactive CLI `semantic-release-cli`](https://github.com/semantic-release/cli).
+
+First install `semantic-release-cli`:
+```bash
+$ npm install -g semantic-release-cli
+```
+
+Then go to your project's directory and run the command:
+```bash
+$ cd your-module
+$ semantic-release-cli setup
+```
+The output looks something like this:
+
+![dialogue](../../media/semantic-release-cli.png)
+
+Available options and other information can be found on [`semantic-release-cli`'s doc](https://github.com/semantic-release/cli#semantic-release-cli).
+
+> **Note**: only a limited number of options, CI services and plugins are currently supported by `semantic-release-cli`.

package/docs/01-usage/installation.md

@@ -0,0 +1,22 @@
+# 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](../05-support/FAQ.md#what-is-npx) for more details.
+
+## Global installation
+
+> **Note:** Global installation is no longer recommended. Please use local installation and `npx` instead.
+

package/docs/{usage → 01-usage}/plugins.md

@@ -1,13 +1,15 @@
 # Plugins
 
-Each [release step](../../README.md#release-steps) is implemented by configurable plugins. This allows for support of different [commit message formats](../../README.md#commit-message-format), release note generators and publishing platforms.
+## Plugins implement actions for release steps
 
-A plugin is a npm module that can implement one or more of the following steps:
+Actions that should be performed for each [release step](../../README.md#release-steps) are implemented through configurable plugins, and [a number of them are installed by default](#plugins-installed-by-default). This allows for support of different [commit message formats](../../README.md#commit-message-format), release note generators and publishing platforms.
 
-| Step               | Required | Description                                                                                                                                                                                                          |
+A plugin is a npm module (for instance `@semantic-release/github` or `semantic-release-docker`) that can implement one or more of the following steps through their step hooks:
+
+| Step hook          | Required | Description                                                                                                                                                                                                          |
 |--------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `verifyConditions` | No       | Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc...                                                                         |
-| `analyzeCommits`   | Yes      | Responsible for determining the type of the next release (`major`, `minor` or `patch`). If multiple plugins with a `analyzeCommits` step are defined, the release type will be the highest one among plugins output. |
+| `analyzeCommits`   | Yes      | Responsible for determining the type of the next release (`major`, `minor` or `patch`). If multiple plugins with a `analyzeCommits` step are defined, the release type will be the highest one among plugins output. <br> **Note**: If no plugin with an `analyzeCommits` step is defined, then `@semantic-release/commit-analyzer` will be used.|
 | `verifyRelease`    | No       | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published.                                                                                              |
 | `generateNotes`    | No       | Responsible for generating the content of the release note. If multiple plugins with a `generateNotes` step are defined, the release notes will be the result of the concatenation of each plugin output.            |
 | `prepare`          | No       | Responsible for preparing the release, for example creating or updating files such as `package.json`, `CHANGELOG.md`, documentation or compiled assets and pushing a commit.                                         |
@@ -15,10 +17,10 @@ A plugin is a npm module that can implement one or more of the following steps:
 | `success`          | No       | Responsible for notifying of a new release.                                                                                                                                                                          |
 | `fail`             | No       | Responsible for notifying of a failed release.                                                                                                                                                                       |
 
-**Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used.
-
 ## Plugins installation
 
+### Plugins installed by default
+
 These five plugins are already part of **semantic-release** and don't have to be installed separately:
 ```
 "@semantic-release/commit-analyzer"	
@@ -28,26 +30,19 @@ These five plugins are already part of **semantic-release** and don't have to be
 "@semantic-release/release-notes-generator"
 ```
 
-[Additional plugins](../extending/plugins-list.md) have to be installed via npm:
+### Installing additional plugins
+
+[Additional plugins](../02-extending/plugins-list.md) have to be installed via npm:
 
 ```bash
 $ npm install @semantic-release/git @semantic-release/changelog -D
 ```
 
-## Plugins configuration
-
-Each plugin must be configured with the [`plugins` options](./configuration.md#plugins) by specifying the list of plugins by npm module name.
-
-```json
-{
-  "plugins": ["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm"]
-}
-```
-
-## Plugin ordering
+## Plugins declaration and execution order
 
-For each [release step](../../README.md#release-steps) the plugins that implement that step will be executed in the order in which the are defined.
+Each plugin (which is an npm module) must be declared using the [`plugins` option](./configuration.md#plugins). If the `plugins` option is defined, then the default is overriden (rather than merge with the option's default).
 
+For example:
 ```json
 {
   "plugins": [
@@ -59,16 +54,18 @@ For each [release step](../../README.md#release-steps) the plugins that implemen
 }
 ```
 
-With this configuration **semantic-release** will:
+For each [release step](../../README.md#release-steps) the plugins that implement that step will be executed **in the order in which they are declared**.
+
+Hence, with this configuration above, **semantic-release** will:
 - execute the `verifyConditions` implementation of `@semantic-release/npm` then `@semantic-release/git`
 - execute the `analyzeCommits` implementation of `@semantic-release/commit-analyzer`
 - execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git`
 - execute the `generateNotes` implementation of `@semantic-release/release-notes-generator`
 - execute the `publish` implementation of `@semantic-release/npm`
 
-## Plugin options
+## Plugins configuration options
 
-A plugin options can specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.
+A plugin configuration options can specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.
 
 Global plugin options can defined at the root of the **semantic-release** configuration object. Options configured this way will be passed to all plugins.
 

package/docs/01-usage/shareable-configurations.md

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