diff --git a/README.md b/README.md index 7110e699..df97a25f 100644 --- a/README.md +++ b/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) diff --git a/docs/extending/plugins-list.md b/docs/extending/plugins-list.md index 5e92ee95..cff3fa19 100644 --- a/docs/extending/plugins-list.md +++ b/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 - - [publish](https://github.com/semantic-release/gitlab#publish): Publish a [GitLab release](https://docs.gitlab.com/ce/workflow/releases.html) + - `verifyConditions`: Verify the presence and the validity of the GitLab authentication and release configuration + - `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 - - [prepare](https://github.com/semantic-release/git#prepare): Push a release commit and tag, including configurable files + - `verifyConditions`: Verify the presence and the validity of the Git authentication and release configuration + - `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 - - [prepare](https://github.com/semantic-release/changelog#prepare): Create or update the changelog file in the local project repository + - `verifyConditions`: Verify the presence and the validity of the configuration + - `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 - - [analyzeCommits](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to determine the type of release - - [verifyRelease](https://github.com/semantic-release/exec#verifyrelease): Execute a shell command to verifying a release that was determined before and is about to be published. - - [generateNotes](https://github.com/semantic-release/exec#analyzecommits): Execute a shell command to generate the release note - - [prepare](https://github.com/semantic-release/exec#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 - - [success](https://github.com/semantic-release/exec#success): Execute a shell command to notify of a new release - - [fail](https://github.com/semantic-release/exec#fail): Execute a shell command to notify of a failed release + - `verifyConditions`: Execute a shell command to verify if the release should happen + - `analyzeCommits`: Execute a shell command to determine the type of release + - `verifyRelease`: Execute a shell command to verifying a release that was determined before and is about to be published. + - `generateNotes`: Execute a shell command to generate the release note + - `prepare`: Execute a shell command to prepare the release + - `publish`: Execute a shell command to publish the release + - `success`: Execute a shell command to notify of a new 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 - - [verifyConditions](https://github.com/felixfbecker/semantic-release-docker#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. -- [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 - - [verifyConditions](https://github.com/carlos-cubas/semantic-release-gcr#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. -- [semantic-release-vsce](https://github.com/raix/semantic-release-vsce) Set of semantic-release plugins for publishing Visual Studio Code extensions to the marketplace - - **verifyConditions** Verify the presence and the validity of the vsce authentication and release configuration - - **prepare** Create a `.vsix` for distribution - - **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 -- [semantic-release-chrome](https://github.com/GabrielDuarteM/semantic-release-chrome) Set of semantic-release plugins for publishing a Chrome extension release. - - [verifyConditions](https://github.com/GabrielDuarteM/semantic-release-chrome#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. - - [publish](https://github.com/GabrielDuarteM/semantic-release-chrome#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. - - [verifyConditions](https://github.com/felixfbecker/semantic-release-firefox#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. - - [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. -- [semantic-release-gerrit](https://github.com/pascalMN/semantic-release-gerrit) Set of semantic-release plugins for projects in the Gerrit repositories. - - [generateNotes](https://github.com/pascalMN/semantic-release-gerrit#generatenotes) Generate release notes with Gerrit reviews URL. \ No newline at end of file +- [semantic-release-docker](https://github.com/felixfbecker/semantic-release-docker) + - `verifyConditions`: Verify that all needed configuration is present and login to the Docker registry. + - `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) + - `verifyConditions`: Verify that all needed configuration is present and login to the Docker registry. + - `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) + - `verifyConditions`: Verify the presence and the validity of the vsce authentication and release configuration + - `prepare`: Create a `.vsix` for distribution + - `publish`: Publish the package to the Visual Studio Code marketplace +- [semantic-release-verify-deps](https://github.com/piercus/semantic-release-verify-deps) + - `verifyConditions`: Check the dependencies format against a regexp before a release +- [semantic-release-chrome](https://github.com/GabrielDuarteM/semantic-release-chrome) + - `verifyConditions`: Verify the presence of the authentication (set via environment variables) + - `prepare`: Write the correct version to the manifest.json and creates a zip file of the whole dist folder + - `publish`: Uploads the generated zip file to the webstore, and publish the item +- [semantic-release-firefox](https://github.com/felixfbecker/semantic-release-firefox) + - `verifyConditions`: Verify the presence of the authentication (set via environment variables) + - `prepare`: Write the correct version to the manifest.json, creates a xpi file of the dist folder and a zip of the sources + - `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) + - `generateNotes`: Generate release notes with Gerrit reviews URL diff --git a/docs/usage/README.md b/docs/usage/README.md index 91208c65..636326ff 100644 --- a/docs/usage/README.md +++ b/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) diff --git a/docs/usage/ci-configuration.md b/docs/usage/ci-configuration.md index 7b708b76..af1bb80a 100644 --- a/docs/usage/ci-configuration.md +++ b/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. diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md index 6db546f8..201b7c28 100644 --- a/docs/usage/configuration.md +++ b/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`
-Default: `['@semantic-release/npm', '@semantic-release/github']`
-CLI argument: `--verify-conditions` - -Define the list of [verify conditions plugins](plugins.md#verifyconditions-plugin). Plugins will run in series, in the order defined in the `Array`. - -See [Plugins configuration](plugins.md#configuration) for more details. - -### analyzeCommits - -Type: `String`, `Object`
-Default: `'@semantic-release/commit-analyzer'`
-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`
-Default: `[]`
-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`
-Default: `['@semantic-release/release-notes-generator']`
-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`
-Default: `['@semantic-release/npm']`
-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`
-Default: `['@semantic-release/npm', '@semantic-release/github']`
-CLI argument: `--publish` - -Define the list of [publish plugins](plugins.md#publish-plugin). Plugins will run in series, in the order defined in the `Array`. - -See [Plugins configuration](plugins.md#configuration) for more details. - -### success - -Type: `Array`, `String`, `Object`
-Default: `['@semantic-release/github']`
-CLI argument: `--success` - -Define the list of [success plugins](plugins.md#success-plugin). Plugins will run in series, in the order defined in the `Array`. - -See [Plugins configuration](plugins.md#configuration) for more details. - -### fail - -Type: `Array`, `String`, `Object`
-Default: `['@semantic-release/github']`
-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. +| 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. | diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md new file mode 100644 index 00000000..e715eeca --- /dev/null +++ b/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`. diff --git a/lib/plugins/index.js b/lib/plugins/index.js index 7f7e5708..5570f12f 100644 --- a/lib/plugins/index.js +++ b/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 { diff --git a/test/plugins/plugins.test.js b/test/plugins/plugins.test.js index b42c39d4..249574d2 100644 --- a/test/plugins/plugins.test.js +++ b/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'}];