docs: add a Getting started section and clarify config steps

README.md

@@ -98,6 +98,7 @@ After running the tests, the command `semantic-release` will execute the followi
 ## 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)

docs/extending/plugins-list.md

@@ -1,61 +1,61 @@
 # Plugins list
 
-## Default plugins
-
-- [@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
-  - [prepare](https://github.com/semantic-release/npm#prepare): Update the package.json version and create the npm package tarball
-  - [publish](https://github.com/semantic-release/npm#publish): Publish the package on the npm registry
-
 ## Official plugins
-
+- [@semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer)
+  - `analyzeCommits`: Determine the type of release by analyzing commits with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
+- [@semantic-release/release-notes-generator](https://github.com/semantic-release/release-notes-generator)
+  - `generateNotes`: Generate release notes for the commits added since the last release with [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog)
+- [@semantic-release/github](https://github.com/semantic-release/github)
+  - `verifyConditions`: Verify the presence and the validity of the GitHub authentication and release configuration
+  - `publish`: Publish a [GitHub release](https://help.github.com/articles/about-releases)
+  - `success`: Add a comment to GitHub issues and pull requests resolved in the release
+  - `fail`: Open a GitHub issue when a release fails
+- [@semantic-release/npm](https://github.com/semantic-release/npm)
+  - `verifyConditions`: Verify the presence and the validity of the npm authentication and release configuration
+  - `prepare`: Update the package.json version and create the npm package tarball
+  - `publish`: Publish the package on the npm registry
 - [@semantic-release/gitlab](https://github.com/semantic-release/gitlab)
-  - [verifyConditions](https://github.com/semantic-release/gitlab#verifyconditions): Verify the presence and the validity of the GitLab authentication and release configuration
+  - `verifyConditions`: Verify the presence and the validity of the GitLab authentication and release configuration
-  - [publish](https://github.com/semantic-release/gitlab#publish): Publish a [GitLab release](https://docs.gitlab.com/ce/workflow/releases.html)
+  - `publish`: Publish a [GitLab release](https://docs.gitlab.com/ce/workflow/releases.html)
 - [@semantic-release/git](https://github.com/semantic-release/git)
-  - [verifyConditions](https://github.com/semantic-release/git#verifyconditions): Verify the presence and the validity of the Git authentication and release configuration
+  - `verifyConditions`: Verify the presence and the validity of the Git authentication and release configuration
-  - [prepare](https://github.com/semantic-release/git#prepare): Push a release commit and tag, including configurable files
+  - `prepare`: Push a release commit and tag, including configurable files
 - [@semantic-release/changelog](https://github.com/semantic-release/changelog)
-  - [verifyConditions](https://github.com/semantic-release/changelog#verifyconditions): Verify the presence and the validity of the configuration
+  - `verifyConditions`: Verify the presence and the validity of the configuration
-  - [prepare](https://github.com/semantic-release/changelog#prepare): Create or update the changelog file in the local project repository
+  - `prepare`: Create or update the changelog file in the local project repository
 - [@semantic-release/exec](https://github.com/semantic-release/exec)
-  - [verifyConditions](https://github.com/semantic-release/exec#verifyconditions): Execute a shell command to verify if the release should happen
+  - `verifyConditions`: Execute a shell command to verify if the release should happen
-  - [analyzeCommits](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to determine the type of release
+  - `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.
+  - `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
+  - `generateNotes`: Execute a shell command to generate the release note
-  - [prepare](https://github.com/semantic-release/exec#prepare): Execute a shell command to prepare the release
+  - `prepare`: Execute a shell command to prepare the release
-  - [publish](https://github.com/semantic-release/exec#publish): Execute a shell command to publish the release
+  - `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
+  - `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
+  - `fail`: Execute a shell command to notify of a failed release
 
 ## Community plugins
 
 [Open a Pull Request](https://github.com/semantic-release/semantic-release/blob/caribou/CONTRIBUTING.md#submitting-a-pull-request) to add your plugin to the list.
 
-- [semantic-release-docker](https://github.com/felixfbecker/semantic-release-docker) Set of semantic-release plugins for publishing a docker image to Docker Hub
+- [semantic-release-docker](https://github.com/felixfbecker/semantic-release-docker)
-  - [verifyConditions](https://github.com/felixfbecker/semantic-release-docker#verifyconditions) Verify that all needed configuration is present and login to the Docker registry.
+  - `verifyConditions`: Verify that all needed configuration is present and login to the Docker registry.
-  - [publish](https://github.com/felixfbecker/semantic-release-docker#publish) Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag.
+  - `publish`: Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag.
-- [semantic-release-gcr](https://github.com/carlos-cubas/semantic-release-gcr) Set of semantic-release plugins for publishing a docker image to Google Container Registry
+- [semantic-release-gcr](https://github.com/carlos-cubas/semantic-release-gcr)
-  - [verifyConditions](https://github.com/carlos-cubas/semantic-release-gcr#verifyconditions) Verify that all needed configuration is present and login to the Docker registry.
+  - `verifyConditions`: Verify that all needed configuration is present and login to the Docker registry.
-  - [publish](https://github.com/carlos-cubas/semantic-release-gcr#publish) Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag.
+  - `publish`: Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag.
-- [semantic-release-vsce](https://github.com/raix/semantic-release-vsce) Set of semantic-release plugins for publishing Visual Studio Code extensions to the marketplace
+- [semantic-release-vsce](https://github.com/raix/semantic-release-vsce)
-  - **verifyConditions** Verify the presence and the validity of the vsce authentication and release configuration
+  - `verifyConditions`: Verify the presence and the validity of the vsce authentication and release configuration
-  - **prepare** Create a `.vsix` for distribution
+  - `prepare`: Create a `.vsix` for distribution
-  - **publish** Publish the package to the Visual Studio Code marketplace
+  - `publish`: Publish the package to the Visual Studio Code marketplace
 - [semantic-release-verify-deps](https://github.com/piercus/semantic-release-verify-deps)
-  - [verifyConditions](https://github.com/piercus/semantic-release-verify-deps) Check the dependencies format against a regexp before a release
+  - `verifyConditions`: Check the dependencies format against a regexp before a release
-- [semantic-release-chrome](https://github.com/GabrielDuarteM/semantic-release-chrome) Set of semantic-release plugins for publishing a Chrome extension release.
+- [semantic-release-chrome](https://github.com/GabrielDuarteM/semantic-release-chrome)
-  - [verifyConditions](https://github.com/GabrielDuarteM/semantic-release-chrome#verifyconditions) Verify the presence of the authentication (set via environment variables).
+  - `verifyConditions`: Verify the presence of the authentication (set via environment variables)
-  - [prepare](https://github.com/GabrielDuarteM/semantic-release-chrome#prepare) Write the correct version to the manifest.json and creates a zip file of the whole dist folder.
+  - `prepare`: Write the correct version to the manifest.json and creates a zip file of the whole dist folder
-  - [publish](https://github.com/GabrielDuarteM/semantic-release-chrome#publish) Uploads the generated zip file to the webstore, and publish the item.
+  - `publish`: Uploads the generated zip file to the webstore, and publish the item
-- [semantic-release-firefox](https://github.com/felixfbecker/semantic-release-firefox) Set of semantic-release plugins for publishing a Firefox extension release.
+- [semantic-release-firefox](https://github.com/felixfbecker/semantic-release-firefox)
-  - [verifyConditions](https://github.com/felixfbecker/semantic-release-firefox#verifyconditions) Verify the presence of the authentication (set via environment variables).
+  - `verifyConditions`: Verify the presence of the authentication (set via environment variables)
-  - [prepare](https://github.com/felixfbecker/semantic-release-firefox#prepare) Write the correct version to the manifest.json,   creates a xpi file of the dist folder and a zip of the sources.
+  - `prepare`: Write the correct version to the manifest.json,   creates a xpi file of the dist folder and a zip of the sources
-  - [publish](https://github.com/felixfbecker/semantic-release-firefox#publish) Submit the generated archives to the webstore for review, and publish the item including release notes.
+  - `publish`: Submit the generated archives to the webstore for review, and publish the item including release notes
-- [semantic-release-gerrit](https://github.com/pascalMN/semantic-release-gerrit) Set of semantic-release plugins for projects in the Gerrit repositories.
+- [semantic-release-gerrit](https://github.com/pascalMN/semantic-release-gerrit)
-  - [generateNotes](https://github.com/pascalMN/semantic-release-gerrit#generatenotes) Generate release notes with Gerrit reviews URL.
+  - `generateNotes`: Generate release notes with Gerrit reviews URL

docs/usage/README.md

@@ -1,5 +1,6 @@
 # Usage
 
+- [Getting started](getting-started.md#getting-started)
 - [Installation](installation.md#installation)
 - [CI Configuration](ci-configuration.md#ci-configuration)
 - [Configuration](configuration.md#configuration)

docs/usage/ci-configuration.md

@@ -31,18 +31,3 @@ See each plugin documentation for the environment variables to set up.
 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.
-
-## Automatic setup with `semantic-release-cli`
-
-[`semantic-release-cli`](https://github.com/semantic-release/cli) allows for easy [installation](installation.md) of **semantic-release** in your Node project as well as setting up the CI configuration:
-
-```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.

docs/usage/configuration.md

@@ -1,19 +1,25 @@
 # Configuration
 
-In order to customize **semantic-release**’s behavior, [options](#options) and [plugins](plugins.md) can be set via:
+**semantic-release** configuration consist 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))
+
+All those options can be configured directly or 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
+
+**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
-- CLI arguments
+
+Alternatively some options can be set via CLI arguments.
 
 The following three examples are the same.
 
-Via CLI argument:
-
-```bash
-$ semantic-release --branch next
-```
-
 Via `release` key in the project's `package.json` file:
 
 ```json
@@ -38,21 +44,18 @@ Via `.releaserc` file:
 $ semantic-release
 ```
 
+Via CLI argument:
+
+```bash
+$ semantic-release --branch next
+```
+
 **Note**: CLI arguments take precedence over options configured in the configuration file.
 
 **Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
 
 **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.
 
-## Environment variables
-
-| Variable              | Description                                                                                                                                                                                                                    | Default                              |
-|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
-| `GIT_AUTHOR_NAME`     | The author 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_AUTHOR_EMAIL`    | The author 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. |
-| `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. |
-
 ## Options
 
 ### extends
@@ -130,82 +133,11 @@ CLI argument: `--debug`
 
 Output debugging information. It can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.
 
-### verifyConditions
+## Git environment variables
 
-Type: `Array`, `String`, `Object`<br>
+| Variable              | Description                                                                                                                                                                                                                    | Default                              |
-Default: `['@semantic-release/npm', '@semantic-release/github']`<br>
+|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------|
-CLI argument: `--verify-conditions`
+| `GIT_AUTHOR_NAME`     | The author 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_AUTHOR_EMAIL`    | The author 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. |
-Define the list of [verify conditions plugins](plugins.md#verifyconditions-plugin). Plugins will run in series, in the order defined in the `Array`.
+| `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. |
-See [Plugins configuration](plugins.md#configuration) for more details.
-
-### analyzeCommits
-
-Type: `String`, `Object`<br>
-Default: `'@semantic-release/commit-analyzer'`<br>
-CLI argument: `--analyze-commits`
-
-Define the [analyze commits plugin](plugins.md#analyzecommits-plugin).
-
-See [Plugins configuration](plugins.md#configuration) for more details.
-
-### verifyRelease
-
-Type: `Array`, `String`, `Object`<br>
-Default: `[]`<br>
-CLI argument: `--verify-release`
-
-Define the list of [verify release plugins](plugins.md#verifyrelease-plugin). Plugins will run in series, in the order defined in the `Array`.
-
-See [Plugins configuration](plugins.md#configuration) for more details.
-
-### generateNotes
-
-Type: `Array`, `String`, `Object`<br>
-Default: `['@semantic-release/release-notes-generator']`<br>
-CLI argument: `--generate-notes`
-
-Define the [generate notes plugins](plugins.md#generatenotes-plugin).
-
-See [Plugins configuration](plugins.md#configuration) for more details.
-
-### prepare
-
-Type: `Array`, `String`, `Object`<br>
-Default: `['@semantic-release/npm']`<br>
-CLI argument: `--prepare`
-
-Define the list of [prepare plugins](plugins.md#prepare-plugin). Plugins will run in series, in the order defined in the `Array`.
-
-See [Plugins configuration](plugins.md#configuration) for more details.
-
-### publish
-
-Type: `Array`, `String`, `Object`<br>
-Default: `['@semantic-release/npm', '@semantic-release/github']`<br>
-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`<br>
-Default: `['@semantic-release/github']`<br>
-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`<br>
-Default: `['@semantic-release/github']`<br>
-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.

docs/usage/getting-started.md

@@ -0,0 +1,22 @@
+# Getting started
+
+In order to use **semantic-release** you must follows this 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 is currently supported by `semantic-release-cli`.

lib/plugins/index.js

@@ -19,7 +19,7 @@ module.exports = (context, pluginsPath) => {
           if (isPlainObject(plugin)) {
             Object.entries(plugin).forEach(([type, func]) => {
               if (PLUGINS_DEFINITIONS[type]) {
-                plugins[type] = [...(plugins[type] || []), [func, config]];
+                plugins[type] = [...(PLUGINS_DEFINITIONS[type].multiple ? plugins[type] || [] : []), [func, config]];
               }
             });
           } else {

test/plugins/plugins.test.js

@@ -105,6 +105,26 @@ test('Export plugins based on "plugins" config (single definition)', async t =>
   t.is(typeof plugins.fail, 'function');
 });
 
+test('Use only last definition of single plugin steps declared in "plugins" config', async t => {
+  const plugin1 = {analyzeCommits: stub()};
+  const plugin2 = {analyzeCommits: stub()};
+  const plugins = getPlugins({cwd, logger: t.context.logger, options: {plugins: [plugin1, plugin2]}}, {});
+
+  await plugins.analyzeCommits({commits: []});
+  t.true(plugin1.analyzeCommits.notCalled);
+  t.true(plugin2.analyzeCommits.calledOnce);
+
+  // Verify the module returns a function for each plugin
+  t.is(typeof plugins.verifyConditions, 'function');
+  t.is(typeof plugins.analyzeCommits, 'function');
+  t.is(typeof plugins.verifyRelease, 'function');
+  t.is(typeof plugins.generateNotes, 'function');
+  t.is(typeof plugins.prepare, 'function');
+  t.is(typeof plugins.publish, 'function');
+  t.is(typeof plugins.success, 'function');
+  t.is(typeof plugins.fail, 'function');
+});
+
 test('Merge global options, "plugins" options and sptep options', async t => {
   const plugin1 = [{verifyConditions: stub(), publish: stub()}, {pluginOpt1: 'plugin1'}];
   const plugin2 = [{verifyConditions: stub()}, {pluginOpt2: 'plugin2'}];