diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e075f621e6..7c9367a305 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,7 @@ Help us keep **semantic-release** open and inclusive. Please read and follow our ### Improve documentation -As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/03-recipes/README.md), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+). +As a **semantic-release** user, you are the perfect candidate to help us improve our documentation: typo corrections, clarifications, more examples, new [recipes](docs/recipes/README.md), etc. Take a look at the [documentation issues that need help](https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Asemantic-release+archived%3Afalse+label%3A%22help+wanted%22+label%3Adocs+). Please follow the [Documentation guidelines](#documentation). @@ -37,7 +37,7 @@ Confirmed bugs and ready-to-implement features are marked with the [help wanted ## Using the issue tracker -The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only. Please use the [Support](docs/05-support/README.md) and [Get help](README.md#get-help) sections for support, troubleshooting and questions. +The issue tracker is the channel for [bug reports](#bug-report), [features requests](#feature-request) and [submitting pull requests](#submitting-a-pull-request) only. Please use the [Support](docs/support/README.md) and [Get help](README.md#get-help) sections for support, troubleshooting and questions. Before opening an issue or a Pull Request, please use the [GitHub issue search](https://github.com/issues?utf8=%E2%9C%93&q=user%3Asemantic-release) to make sure the bug or feature request hasn't been already reported or fixed. @@ -51,7 +51,7 @@ Feature requests are welcome, but take a moment to find out whether your idea fi ### New plugin request -[Plugins](docs/01-usage/plugins.md) are a great way to extend **semantic-release** capabilities, integrate with other systems and support new project type. Please provide as much detail and context as possible and fill the information requested in the [New plugin request template](https://github.com/semantic-release/semantic-release/issues/new?template=plugin-request.md). +[Plugins](docs/usage/plugins.md) are a great way to extend **semantic-release** capabilities, integrate with other systems and support new project type. Please provide as much detail and context as possible and fill the information requested in the [New plugin request template](https://github.com/semantic-release/semantic-release/issues/new?template=plugin-request.md). ## Submitting a Pull Request diff --git a/README.md b/README.md index aeccdf9191..de9807ec14 100644 --- a/README.md +++ b/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/03-recipes/README.md#ci-configurations) +- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations) - Avoid potential errors associated with manual releases -- Support any [package managers and languages](docs/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) +- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md) +- Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md) ## How does it work? @@ -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/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. +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. 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. @@ -78,48 +78,48 @@ If you need more control over the timing of releases you have a couple of option After running the tests, the command `semantic-release` will execute the following steps: -| 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. | +| 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. | ## Documentation - Usage - - [Getting started](docs/01-usage/01-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) + - [Getting started](docs/usage/getting-started.md) + - [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) - Extending - - [Plugins](docs/02-extending/plugins-list.md) - - [Shareable configuration](docs/02-extending/shareable-configurations-list.md) + - [Plugins](docs/extending/plugins-list.md) + - [Shareable configuration](docs/extending/shareable-configurations-list.md) - Recipes - - [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) + - [CI configurations](docs/recipes/ci-configurations.md) + - [CircleCI 2.0 workflows](docs/recipes/circleci-workflows.md) + - [Travis CI](docs/recipes/travis.md) + - [GitLab CI](docs/recipes/gitlab-ci.md) + - [Git hosted services](docs/recipes/git-hosted-services.md) + - [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md) + - [Package managers and languages](docs/recipes/package-managers-and-languages.md) - Developer guide - - [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) + - [JavaScript API](docs/developer-guide/js-api.md) + - [Plugin development](docs/developer-guide/plugin.md) + - [Shareable configuration development](docs/developer-guide/shareable-configuration.md) - Support - - [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) + - [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) ## Get help diff --git a/SUMMARY.md b/SUMMARY.md index 74e4089e52..c6597ab50e 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,34 +1,34 @@ # Summary ## Usage -- [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) +- [Getting started](docs/usage/getting-started.md) +- [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) -## Extensions -- [Plugins](docs/02-extending/plugins-list.md) -- [Shareable configuration](docs/02-extending/shareable-configurations-list.md) +## Extending +- [Plugins](docs/extending/plugins-list.md) +- [Shareable configuration](docs/extending/shareable-configurations-list.md) ## Recipes -- [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) +- [CI configurations](docs/recipes/ci-configurations.md) + - [CircleCI 2.0 workflows](docs/recipes/circleci-workflows.md) + - [Travis CI](docs/recipes/travis.md) + - [GitLab CI](docs/recipes/gitlab-ci.md) +- [Git hosted services](docs/recipes/git-hosted-services.md) + - [Git authentication with SSH keys](docs/recipes/git-auth-ssh-keys.md) +- [Package managers and languages](docs/recipes/package-managers-and-languages.md) ## Developer guide -- [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) +- [JavaScript API](docs/developer-guide/js-api.md) +- [Plugin development](docs/developer-guide/plugin.md) +- [Shareable configuration development](docs/developer-guide/shareable-configuration.md) ## Support -- [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) +- [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) diff --git a/docs/01-usage/getting-started.md b/docs/01-usage/getting-started.md deleted file mode 100644 index 26e5a8ad81..0000000000 --- a/docs/01-usage/getting-started.md +++ /dev/null @@ -1,32 +0,0 @@ -# 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`. diff --git a/docs/01-usage/installation.md b/docs/01-usage/installation.md deleted file mode 100644 index 64c27260b6..0000000000 --- a/docs/01-usage/installation.md +++ /dev/null @@ -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](../05-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](../05-support/FAQ.md#what-is-npx) for more details. diff --git a/docs/README.md b/docs/README.md index abc9b8ee9b..a5b4380e97 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # semantic-release documentation -- [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 +- [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 diff --git a/docs/04-developer-guide/README.md b/docs/developer-guide/README.md similarity index 100% rename from docs/04-developer-guide/README.md rename to docs/developer-guide/README.md diff --git a/docs/04-developer-guide/js-api.md b/docs/developer-guide/js-api.md similarity index 96% rename from docs/04-developer-guide/js-api.md rename to docs/developer-guide/js-api.md index cf362ab9b6..33b041759d 100644 --- a/docs/04-developer-guide/js-api.md +++ b/docs/developer-guide/js-api.md @@ -65,9 +65,9 @@ Type: `Object` **semantic-release** options. -Can be used to set any [core option](../01-usage/configuration.md#configuration) or [plugin options](../01-usage/plugins.md#configuration). +Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration). -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). +Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends). #### config @@ -229,7 +229,7 @@ Example: Type: `Array` -The list of releases published, one release per [publish plugin](../01-usage/plugins.md#publish-plugin).
+The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).
Each release object has the following properties: | Name | Type | Description | diff --git a/docs/04-developer-guide/plugin.md b/docs/developer-guide/plugin.md similarity index 100% rename from docs/04-developer-guide/plugin.md rename to docs/developer-guide/plugin.md diff --git a/docs/04-developer-guide/shareable-configuration.md b/docs/developer-guide/shareable-configuration.md similarity index 100% rename from docs/04-developer-guide/shareable-configuration.md rename to docs/developer-guide/shareable-configuration.md diff --git a/docs/02-extending/README.md b/docs/extending/README.md similarity index 100% rename from docs/02-extending/README.md rename to docs/extending/README.md diff --git a/docs/02-extending/plugins-list.md b/docs/extending/plugins-list.md similarity index 100% rename from docs/02-extending/plugins-list.md rename to docs/extending/plugins-list.md diff --git a/docs/02-extending/shareable-configurations-list.md b/docs/extending/shareable-configurations-list.md similarity index 100% rename from docs/02-extending/shareable-configurations-list.md rename to docs/extending/shareable-configurations-list.md diff --git a/docs/03-recipes/README.md b/docs/recipes/README.md similarity index 100% rename from docs/03-recipes/README.md rename to docs/recipes/README.md diff --git a/docs/03-recipes/ci-configurations-recipes.md b/docs/recipes/ci-configurations.md similarity index 100% rename from docs/03-recipes/ci-configurations-recipes.md rename to docs/recipes/ci-configurations.md diff --git a/docs/03-recipes/circleci-workflows.md b/docs/recipes/circleci-workflows.md similarity index 75% rename from docs/03-recipes/circleci-workflows.md rename to docs/recipes/circleci-workflows.md index 8c2aefc719..a83a2a31d4 100644 --- a/docs/03-recipes/circleci-workflows.md +++ b/docs/recipes/circleci-workflows.md @@ -2,9 +2,9 @@ ## Environment variables -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).. +The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [CircleCi Project Settings](https://circleci.com/docs/2.0/env-vars/#adding-environment-variables-in-the-app).. -Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../01-usage/01-getting-started.md#getting-started). +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started). ## 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](../01-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](../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](../01-usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. ```json { diff --git a/docs/03-recipes/git-auth-ssh-keys.md b/docs/recipes/git-auth-ssh-keys.md similarity index 93% rename from docs/03-recipes/git-auth-ssh-keys.md rename to docs/recipes/git-auth-ssh-keys.md index 1365f2b403..f346d802ab 100644 --- a/docs/03-recipes/git-auth-ssh-keys.md +++ b/docs/recipes/git-auth-ssh-keys.md @@ -1,6 +1,6 @@ # Git authentication with SSH keys -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). +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). 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. diff --git a/docs/03-recipes/git-hosted-services.md b/docs/recipes/git-hosted-services.md similarity index 100% rename from docs/03-recipes/git-hosted-services.md rename to docs/recipes/git-hosted-services.md diff --git a/docs/03-recipes/gitlab-ci.md b/docs/recipes/gitlab-ci.md similarity index 68% rename from docs/03-recipes/gitlab-ci.md rename to docs/recipes/gitlab-ci.md index 349937f01b..6671ecef8b 100644 --- a/docs/03-recipes/gitlab-ci.md +++ b/docs/recipes/gitlab-ci.md @@ -2,19 +2,19 @@ ## Environment 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). +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). ## 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](../05-support/FAQ.md#why-does-semantic-release-require-node-version--83). +**Note**: The publish pipeline must run a [Node >= 8 version](../support/FAQ.md#why-does-semantic-release-require-node-version--83). ### `.gitlab-ci.yml` configuration for Node projects This example is a minimal configuration for **semantic-release** with a build running Node 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](../01-usage/installation.md#local-installation) or [global](../01-usage/installation.md#global-installation) **semantic-release** installation. +**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. ```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](../01-usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. ```json { diff --git a/docs/03-recipes/package-managers-and-languages.md b/docs/recipes/package-managers-and-languages.md similarity index 100% rename from docs/03-recipes/package-managers-and-languages.md rename to docs/recipes/package-managers-and-languages.md diff --git a/docs/03-recipes/travis.md b/docs/recipes/travis.md similarity index 81% rename from docs/03-recipes/travis.md rename to docs/recipes/travis.md index adbe8280f3..02ac8356ba 100644 --- a/docs/03-recipes/travis.md +++ b/docs/recipes/travis.md @@ -2,9 +2,9 @@ ## Environment variables -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). +The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Travis Repository Settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-Settings) or with the [travis env set CLI](https://github.com/travis-ci/travis.rb#env). -Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../01-usage/01-getting-started.md#getting-started). +Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/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](../01-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](../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](../01-usage/installation.md#local-installation) **semantic-release** installation. +A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation. ```json { @@ -57,13 +57,13 @@ A `package.json` is required only for [local](../01-usage/installation.md#local- 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](../05-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](../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](../01-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](../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. diff --git a/docs/05-support/FAQ.md b/docs/support/FAQ.md similarity index 84% rename from docs/05-support/FAQ.md rename to docs/support/FAQ.md index 4b2faed893..f323443e29 100644 --- a/docs/05-support/FAQ.md +++ b/docs/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](../01-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](../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](../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. +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. 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](../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. +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. 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 pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments. +See the [CI configuration recipes](../recipes/ci-configurations.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](../01-usage/installation.md#local-installation) replace +For [local installation](../usage/installation.md#local-installation) replace `npx semantic-release` with `yarn run semantic-release`. -For [global installation](../01-usage/installation.md#global-installation) replace +For [global installation](../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](../01-usage/installation.md#global-installation) repla 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](../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) +- 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) - 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 pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments. +See the [CI configuration recipes](../recipes/ci-configurations.md) for more details on specific CI environments. -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. +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. 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](../03-recipes/README.md#package-managers-and-languages) for more details on specific project types. +See the [package managers and languages recipes](../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](../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) +- 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) -See the [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details on specific CI environments. +See the [CI configuration recipes](../recipes/ci-configurations.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](../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: +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: ```bash $ NPM_TOKEN= GH_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](../03-recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration. +See the [GitLab CI recipes](../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](../01-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](../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](../01-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](../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](/node-version.md#node-version-requirement) for more details and solutions. +See [Node version requirement](../support/node-version.md#node-version-requirement) for more details and solutions. ## What is npx? diff --git a/docs/05-support/README.md b/docs/support/README.md similarity index 100% rename from docs/05-support/README.md rename to docs/support/README.md diff --git a/docs/05-support/node-support-policy.md b/docs/support/node-support-policy.md similarity index 100% rename from docs/05-support/node-support-policy.md rename to docs/support/node-support-policy.md diff --git a/docs/05-support/node-version.md b/docs/support/node-version.md similarity index 91% rename from docs/05-support/node-version.md rename to docs/support/node-version.md index 31f84770a7..e387685b23 100644 --- a/docs/05-support/node-version.md +++ b/docs/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](../01-usage/ci-configuration.md) and [CI pipelines recipes](../03-recipes/ci-pipelines-recipes.md) for more details. +See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/ci-configurations.md) for more details. ## Alternative solutions diff --git a/docs/05-support/resources.md b/docs/support/resources.md similarity index 100% rename from docs/05-support/resources.md rename to docs/support/resources.md diff --git a/docs/05-support/troubleshooting.md b/docs/support/troubleshooting.md similarity index 100% rename from docs/05-support/troubleshooting.md rename to docs/support/troubleshooting.md diff --git a/docs/01-usage/README.md b/docs/usage/README.md similarity index 100% rename from docs/01-usage/README.md rename to docs/usage/README.md diff --git a/docs/01-usage/ci-configuration.md b/docs/usage/ci-configuration.md similarity index 52% rename from docs/01-usage/ci-configuration.md rename to docs/usage/ci-configuration.md index da872f5f7a..036d287b82 100644 --- a/docs/01-usage/ci-configuration.md +++ b/docs/usage/ci-configuration.md @@ -1,29 +1,14 @@ # CI configuration -## Running `semantic-release` +## Run `semantic-release` only after all tests succeeded -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. +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). -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. +See [CI configuration recipes](../recipes/ci-configurations.md) for more details. ## Authentication -### 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: +**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: | Variable | Description | |---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -32,22 +17,17 @@ The Git authentication can be set with one of the following environment variable | `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 `:`. 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](../03-recipes/git-auth-ssh-keys.md)**. +Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-auth-ssh-keys.md). -### 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: +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: | 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).
**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.
**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. -> **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. +The authentication token/credentials have to be made available in the CI service via environment variables. + +See [CI configuration recipes](../recipes/ci-configurations.md) for more details on how to configure environment variables in your CI service. diff --git a/docs/01-usage/configuration.md b/docs/usage/configuration.md similarity index 51% rename from docs/01-usage/configuration.md rename to docs/usage/configuration.md index 23c380d088..8a6da1868b 100644 --- a/docs/01-usage/configuration.md +++ b/docs/usage/configuration.md @@ -1,93 +1,73 @@ # Configuration **semantic-release** configuration consists of: -- 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)). +- 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 of these options can be configured: -- In a config file. -- Through the cli. -- By extending a [shareable configuration](shareable-configurations.md). +All of these 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). -## Configuring/passing options to `semantic-release` +## Configuration file -### 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 -> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration. +Alternatively, some options can be set via CLI arguments. -**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. +The following three examples are the same. -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" - } - } - ``` +Via `release` key in the project's `package.json` file: -### Using CLI arguments +```json +{ + "release": { + "branch": "next" + } +} +``` +```bash +$ semantic-release +``` -> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration. +Via `.releaserc` file: -Plugin options cannot be defined via CLI arguments and must be defined in the configuration file. +```json +{ + "branch": "next" +} +``` +```bash +$ semantic-release +``` -The following configuration example via CLI argument is equivalent to the configuration file's example: +Via CLI argument: ```bash $ semantic-release --branch next ``` -### Extending a shareable configuration +**Note**: CLI arguments take precedence over options configured in the configuration file. -> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration. +**Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file. -Please see [shareable configuration](shareable-configurations.md) for more details. +**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. ## Options -### `extends` +### extends Type: `Array`, `String`
CLI arguments: `-e`, `--extends` -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` +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 Type: `String`
Default: `master`
@@ -95,14 +75,7 @@ CLI arguments: `-b`, `--branch` The branch on which releases should happen. -Example (`.releaserc` file content): -```json -{ - "branch": "next" -} -``` - -### `repositoryUrl` +### repositoryUrl Type: `String`
Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)
@@ -112,14 +85,7 @@ 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)). -Example (`.releaserc` file content): -```json -{ - "repositoryUrl": "https://github.com/username/project.git" -} -``` - -### `tagFormat` +### tagFormat Type: `String`
Default: `v${version}`
@@ -127,41 +93,21 @@ 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). -Example (`.releaserc` file content): -```json -{ - "tagFormat": "version-${version}" -} -``` - -### `plugins` +### plugins Type: `Array`
Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
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. +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. -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. +Plugins configuration can defined by wrapping the name and an options object in an array. -Example (`.releaserc` file content): -```json -{ - "plugins": [ - "@semantic-release/commit-analyzer", - "@semantic-release/release-notes-generator", - "@semantic-release-docker", - ["@semantic-release/exec", { - "verifyConditionsCmd": "./verify.sh" # plugin configuration - }], - "@semantic-release/git", - "@semantic-release/gitlab", - ] -} -``` -### `dryRun` +See [Plugins configuration](plugins.md#plugins) for more details. + +### dryRun Type: `Boolean`
Default: `false` if running in a CI environment, `true` otherwise
@@ -169,14 +115,7 @@ CLI arguments: `-d`, `--dry-run` Dry-run mode, skip publishing, print next version and release notes. -Example (`.releaserc` file content): -```json -{ - "dryRun": "true" -} -``` - -### `ci` +### ci Type: `Boolean`
Default: `true`
@@ -184,16 +123,9 @@ 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`. - -Example (`.releaserc` file content): -```json -{ - "ci": "false" -} -``` +**Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`. -### `debug` (only through CLI) +### debug Type: `Boolean`
Default: `false`
@@ -201,12 +133,7 @@ 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](../04-developer-guide/js-api.md#javascript-api) use `require('debug').enable('semantic-release:*')`. - -Example: -```bash -$ semantic-release --debug -``` +**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:*')`. ## Git environment variables @@ -217,11 +144,9 @@ $ semantic-release --debug | `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, 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. +## Existing version tags -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`). +**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 the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case. diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md new file mode 100644 index 0000000000..f8bda3bb5c --- /dev/null +++ b/docs/usage/getting-started.md @@ -0,0 +1,22 @@ +# 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`. diff --git a/docs/usage/installation.md b/docs/usage/installation.md new file mode 100644 index 0000000000..e51002e783 --- /dev/null +++ b/docs/usage/installation.md @@ -0,0 +1,29 @@ +# 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. diff --git a/docs/01-usage/plugins.md b/docs/usage/plugins.md similarity index 70% rename from docs/01-usage/plugins.md rename to docs/usage/plugins.md index 8f329e465b..9ef56de5ce 100644 --- a/docs/01-usage/plugins.md +++ b/docs/usage/plugins.md @@ -1,15 +1,13 @@ # Plugins -## Plugins implement actions for release steps +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. -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. +A plugin is a npm module that can implement one or more of the following steps: -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 | +| Step | 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.
**Note**: If no plugin with an `analyzeCommits` step is defined, then `@semantic-release/commit-analyzer` will be used.| +| `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. | | `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. | @@ -17,9 +15,9 @@ A plugin is a npm module (for instance `@semantic-release/github` or `semantic-r | `success` | No | Responsible for notifying of a new release. | | `fail` | No | Responsible for notifying of a failed release. | -## Plugins installation +**Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used. -### Plugins installed by default +## Plugins installation These five plugins are already part of **semantic-release** and don't have to be installed separately: ``` @@ -30,19 +28,28 @@ These five plugins are already part of **semantic-release** and don't have to be "@semantic-release/release-notes-generator" ``` -### Installing additional plugins - -[Additional plugins](../02-extending/plugins-list.md) have to be installed via npm: +[Additional plugins](../extending/plugins-list.md) have to be installed via npm: ```bash $ npm install @semantic-release/git @semantic-release/changelog -D ``` -## Plugins declaration and execution order +## Plugins configuration -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). +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"] +} +``` + +**Note:** If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it. + +## Plugin ordering + +For each [release step](../../README.md#release-steps) the plugins that implement that step will be executed in the order in which they are defined. -For example: ```json { "plugins": [ @@ -54,18 +61,16 @@ For example: } ``` -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: +With this configuration **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` -## Plugins configuration options +## Plugin options -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. +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. Global plugin options can defined at the root of the **semantic-release** configuration object. Options configured this way will be passed to all plugins. @@ -75,11 +80,11 @@ Global plugin options can defined at the root of the **semantic-release** config "@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", ["@semantic-release/github", { - "assets": ["dist/**"] # plugin configuration + "assets": ["dist/**"] }], "@semantic-release/git" ], - "preset": "angular" # option passed to all plugins + "preset": "angular" } ``` diff --git a/docs/01-usage/shareable-configurations.md b/docs/usage/shareable-configurations.md similarity index 78% rename from docs/01-usage/shareable-configurations.md rename to docs/usage/shareable-configurations.md index 3e1a3ccfbd..bfaf3bab08 100644 --- a/docs/01-usage/shareable-configurations.md +++ b/docs/usage/shareable-configurations.md @@ -4,4 +4,4 @@ A shareable configuration is an [npm](https://www.npmjs.com/) package that expor The shareable configurations to use can be set with the [extends](configuration.md#extends) option. -See [shareable configurations list](../02-extending/shareable-configurations-list.md). +See [shareable configurations list](../extending/shareable-configurations-list.md).