style: prettier (#2624)
This commit is contained in:
Gregor Martynus
@@ -4,6 +4,7 @@
|
||||
|
||||
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.
|
||||
Here are a few examples of the CI services that can be used to achieve this:
|
||||
|
||||
- [Travis Build Stages](https://docs.travis-ci.com/user/build-stages)
|
||||
- [CircleCI Workflows](https://circleci.com/docs/2.0/workflows)
|
||||
- [GitHub Actions](https://github.com/features/actions)
|
||||
@@ -22,11 +23,11 @@ See [CI configuration recipes](../recipes/ci-configurations#ci-configurations) f
|
||||
**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 |
|
||||
|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `GH_TOKEN` or `GITHUB_TOKEN` | A GitHub [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line). |
|
||||
| `GL_TOKEN` or `GITLAB_TOKEN` | A GitLab [personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html). |
|
||||
| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). |
|
||||
| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. |
|
||||
| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. |
|
||||
| `GIT_CREDENTIALS` | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `<username>:<password>`. The username and password must each be individually URL encoded, not the `:` separating them. |
|
||||
|
||||
Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-hosted-services/git-auth-ssh-keys.md).
|
||||
@@ -36,7 +37,7 @@ Alternatively the Git authentication can be set up via [SSH keys](../recipes/git
|
||||
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).<br/>**Note**: Only the `auth-only` [level of npm two-factor authentication](https://docs.npmjs.com/getting-started/using-two-factor-authentication#levels-of-authentication) is supported. |
|
||||
| `GH_TOKEN` | GitHub authentication token.<br/>**Note**: Only the [personal token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line) authentication is supported. |
|
||||
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Configuration
|
||||
|
||||
**semantic-release** configuration consists of:
|
||||
|
||||
- Git repository ([URL](#repositoryurl) and options [release branches](#branches) and [tag format](#tagformat))
|
||||
- Plugins [declaration](#plugins) and options
|
||||
- Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
|
||||
@@ -12,6 +13,7 @@ Additionally, metadata of Git tags generated by **semantic-release** can be cust
|
||||
## Configuration file
|
||||
|
||||
**semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via either:
|
||||
|
||||
- A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.cjs`
|
||||
- A `release.config.(js|cjs)` file that exports an object
|
||||
- A `release` key in the project's `package.json` file
|
||||
@@ -21,6 +23,7 @@ Alternatively, some options can be set via CLI arguments.
|
||||
The following three examples are the same.
|
||||
|
||||
- Via `release` key in the project's `package.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"release": {
|
||||
@@ -30,6 +33,7 @@ The following three examples are the same.
|
||||
```
|
||||
|
||||
- Via `.releaserc` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"branches": ["master", "next"]
|
||||
@@ -37,6 +41,7 @@ The following three examples are the same.
|
||||
```
|
||||
|
||||
- Via CLI argument:
|
||||
|
||||
```bash
|
||||
$ semantic-release --branches next
|
||||
```
|
||||
@@ -65,10 +70,11 @@ Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name:
|
||||
CLI arguments: `--branches`
|
||||
|
||||
The branches on which releases should happen. By default **semantic-release** will release:
|
||||
|
||||
- regular releases to the default distribution channel from the branch `master`
|
||||
- regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a number)
|
||||
- regular releases to the `next` distribution channel from the branch `next` if it exists
|
||||
- regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
|
||||
- regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
|
||||
- pre-releases to the `beta` distribution channel from the branch `beta` if it exists
|
||||
- pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists
|
||||
|
||||
@@ -143,7 +149,7 @@ Output debugging information. This can also be enabled by setting the `DEBUG` en
|
||||
## Git 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. |
|
||||
|
||||
+10
-4
@@ -5,7 +5,7 @@ Each [release step](../../README.md#release-steps) is implemented by configurabl
|
||||
A plugin is a npm module that can implement one or more of the following steps:
|
||||
|
||||
| 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. |
|
||||
| `verifyRelease` | No | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published. |
|
||||
@@ -25,6 +25,7 @@ Release steps will run in that order. At each step, **semantic-release** will ru
|
||||
### Default plugins
|
||||
|
||||
These four plugins are already part of **semantic-release** and are listed in order of execution. They do not have to be installed separately:
|
||||
|
||||
```
|
||||
"@semantic-release/commit-analyzer"
|
||||
"@semantic-release/release-notes-generator"
|
||||
@@ -66,6 +67,7 @@ For each [release step](../../README.md#release-steps) the plugins that implemen
|
||||
```
|
||||
|
||||
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 `generateNotes` implementation of `@semantic-release/release-notes-generator`
|
||||
@@ -85,9 +87,12 @@ Global plugin configuration can be defined at the root of the **semantic-release
|
||||
"plugins": [
|
||||
"@semantic-release/commit-analyzer",
|
||||
"@semantic-release/release-notes-generator",
|
||||
["@semantic-release/github", {
|
||||
"assets": ["dist/**"]
|
||||
}],
|
||||
[
|
||||
"@semantic-release/github",
|
||||
{
|
||||
"assets": ["dist/**"]
|
||||
}
|
||||
],
|
||||
"@semantic-release/git"
|
||||
],
|
||||
"preset": "angular"
|
||||
@@ -95,5 +100,6 @@ Global plugin configuration can be defined at the root of the **semantic-release
|
||||
```
|
||||
|
||||
With this configuration:
|
||||
|
||||
- All plugins will receive the `preset` option, which will be used by both `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` (and ignored by `@semantic-release/github` and `@semantic-release/git`)
|
||||
- The `@semantic-release/github` plugin will receive the `assets` options (`@semantic-release/git` will not receive it and therefore will use it's default value for that option)
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
# Workflow configuration
|
||||
|
||||
**semantic-release** allow to manage and automate complex release workflow, based on multiple Git branches and distribution channels. This allow to:
|
||||
|
||||
- Distribute certain releases to a particular group of users via distribution channels
|
||||
- Manage the availability of releases on distribution channels via branches merge
|
||||
- Maintain multiple lines of releases in parallel
|
||||
@@ -12,6 +13,7 @@ The release workflow is configured via the [branches option](./configuration.md#
|
||||
Each branch can be defined either as a string, a [glob](https://github.com/micromatch/micromatch#matching-features) or an object. For string and glob definitions each [property](#branches-properties) will be defaulted.
|
||||
|
||||
A branch can defined as one of three types:
|
||||
|
||||
- [release](#release-branches): to make releases on top of the last version released
|
||||
- [maintenance](#maintenance-branches): to make releases on top of an old release
|
||||
- [pre-release](#pre-release-branches): to make pre-releases
|
||||
@@ -21,7 +23,7 @@ The type of the branch is automatically determined based on naming convention an
|
||||
## Branches properties
|
||||
|
||||
| Property | Branch type | Description | Default |
|
||||
|--------------|-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|
|
||||
| ------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `name` | All | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name). | - The value itself if defined as a `String` or the matching branches name if defined as a glob. |
|
||||
| `channel` | All | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones. |
|
||||
| `range` | [maintenance](#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](#range). | The value of `name`. |
|
||||
@@ -35,14 +37,15 @@ It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-
|
||||
If `name` doesn't match to any branch existing in the repository, the definition will be ignored. For example the default configuration includes the definition `next` and `next-major` which will become active only when the branches `next` and/or `next-major` are created in the repository. This allow to define your workflow once with all potential branches you might use and have the effective configuration evolving as you create new branches.
|
||||
|
||||
For example the configuration `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next']` will be expanded as:
|
||||
|
||||
```js
|
||||
{
|
||||
branches: [
|
||||
{name: '1.x', range: '1.x', channel: '1.x'}, // Only after the `1.x` is created in the repo
|
||||
{name: '2.x', range: '2.x', channel: '2.x'}, // Only after the `2.x` is created in the repo
|
||||
{name: 'master'},
|
||||
{name: 'next', channel: 'next'}, // Only after the `next` is created in the repo
|
||||
]
|
||||
{ name: "1.x", range: "1.x", channel: "1.x" }, // Only after the `1.x` is created in the repo
|
||||
{ name: "2.x", range: "2.x", channel: "2.x" }, // Only after the `2.x` is created in the repo
|
||||
{ name: "master" },
|
||||
{ name: "next", channel: "next" }, // Only after the `next` is created in the repo
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -54,12 +57,13 @@ If the `channel` property is set to `false` the default channel will be used.
|
||||
The value of `channel`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
|
||||
|
||||
For example the configuration `['master', {name: 'next', channel: 'channel-${name}'}]` will be expanded as:
|
||||
|
||||
```js
|
||||
{
|
||||
branches: [
|
||||
{name: 'master'}, // `channel` is undefined so the default distribution channel will be used
|
||||
{name: 'next', channel: 'channel-next'}, // `channel` is built with the template `channel-${name}`
|
||||
]
|
||||
{ name: "master" }, // `channel` is undefined so the default distribution channel will be used
|
||||
{ name: "next", channel: "channel-next" }, // `channel` is built with the template `channel-${name}`
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -68,13 +72,14 @@ For example the configuration `['master', {name: 'next', channel: 'channel-${nam
|
||||
A `range` only applies to maintenance branches, is required and must be formatted like `N.N.x` or `N.x` (`N` is a number). In case the `name` is formatted as a range (for example `1.x` or `1.5.x`) the branch will be considered a maintenance branch and the `name` value will be used for the `range`.
|
||||
|
||||
For example the configuration `['1.1.x', '1.2.x', 'master']` will be expanded as:
|
||||
|
||||
```js
|
||||
{
|
||||
branches: [
|
||||
{name: '1.1.x', range: '1.1.x', channel: '1.1.x'},
|
||||
{name: '1.2.x', range: '1.2.x', channel: '1.2.x'},
|
||||
{name: 'master'},
|
||||
]
|
||||
{ name: "1.1.x", range: "1.1.x", channel: "1.1.x" },
|
||||
{ name: "1.2.x", range: "1.2.x", channel: "1.2.x" },
|
||||
{ name: "master" },
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -86,13 +91,14 @@ If the `prerelease` property is set to `true` the `name` value will be used.
|
||||
The value of `prerelease`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
|
||||
|
||||
For example the configuration `['master', {name: 'pre/rc', prerelease: '${name.replace(/^pre\\//g, "")}'}, {name: 'beta', prerelease: true}]` will be expanded as:
|
||||
|
||||
```js
|
||||
{
|
||||
branches: [
|
||||
{name: 'master'},
|
||||
{name: 'pre/rc', channel: 'pre/rc', prerelease: 'rc'}, // `prerelease` is built with the template `${name.replace(/^pre\\//g, "")}`
|
||||
{name: 'beta', channel: 'beta', prerelease: true}, // `prerelease` is set to `beta` as it is the value of `name`
|
||||
]
|
||||
{ name: "master" },
|
||||
{ name: "pre/rc", channel: "pre/rc", prerelease: "rc" }, // `prerelease` is built with the template `${name.replace(/^pre\\//g, "")}`
|
||||
{ name: "beta", channel: "beta", prerelease: true }, // `prerelease` is set to `beta` as it is the value of `name`
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
@@ -113,10 +119,12 @@ See [publishing on distribution channels recipe](../recipes/release-workflow/dis
|
||||
#### Pushing to a release branch
|
||||
|
||||
With the configuration `"branches": ["master", "next"]`, if the last release published from `master` is `1.0.0` and the last one from `next` is `2.0.0` then:
|
||||
|
||||
- Only versions in range `1.x.x` can be published from `master`, so only `fix` and `feat` commits can be pushed to `master`
|
||||
- Once `next` get merged into `master` the release `2.0.0` will be made available on the channel associated with `master` and both `master` and `next` will accept any commit type
|
||||
|
||||
This verification prevent scenario such as:
|
||||
|
||||
1. Create a `feat` commit on `next` which triggers the release of version `1.0.0` on the `next` channel
|
||||
2. Merge `next` into `master` which adds `1.0.0` on the default channel
|
||||
3. Create a `feat` commit on `next` which triggers the release of version `1.1.0` on the `next` channel
|
||||
@@ -147,6 +155,7 @@ See [publishing maintenance releases recipe](../recipes/release-workflow/mainten
|
||||
#### Pushing to a maintenance branch
|
||||
|
||||
With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.5.0` then:
|
||||
|
||||
- Only versions in range `>=1.0.0 <1.1.0` can be published from `1.0.x`, so only `fix` commits can be pushed to `1.0.x`
|
||||
- Only versions in range `>=1.1.0 <1.5.0` can be published from `1.x`, so only `fix` and `feat` commits can be pushed to `1.x` as long the resulting release is lower than `1.5.0`
|
||||
- Once `2.0.0` is released from `master`, versions in range `>=1.1.0 <2.0.0` can be published from `1.x`, so any number of `fix` and `feat` commits can be pushed to `1.x`
|
||||
@@ -154,6 +163,7 @@ With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last rel
|
||||
#### Merging into a maintenance branch
|
||||
|
||||
With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.0.0` then:
|
||||
|
||||
- Creating the branch `1.0.x` from `master` will make the `1.0.0` release available on the `1.0.x` distribution channel
|
||||
- Pushing a `fix` commit on the `1.0.x` branch will release the version `1.0.1` on the `1.0.x` distribution channel
|
||||
- Creating the branch `1.x` from `master` will make the `1.0.0` release available on the `1.x` distribution channel
|
||||
@@ -176,11 +186,13 @@ See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md
|
||||
#### Pushing to a pre-release branch
|
||||
|
||||
With the configuration `"branches": ["master", {"name": "beta", "prerelease": true}]`, if the last release published from `master` is `1.0.0` then:
|
||||
|
||||
- Pushing a `BREAKING CHANGE` commit on the `beta` branch will release the version `2.0.0-beta.1` on the `beta` distribution channel
|
||||
- Pushing either a `fix`, `feat` or a `BREAKING CHANGE` commit on the `beta` branch will release the version `2.0.0-beta.2` (then `2.0.0-beta.3`, `2.0.0-beta.4`, etc...) on the `beta` distribution channel
|
||||
|
||||
#### Merging into a pre-release branch
|
||||
|
||||
With the configuration `"branches": ["master", {"name": "beta", "prerelease": true}]`, if the last release published from `master` is `1.0.0` and the last one published from `beta` is `2.0.0-beta.1` then:
|
||||
|
||||
- Pushing a `fix` commit on the `master` branch will release the version `1.0.1` on the default distribution channel
|
||||
- Merging the branch `master` into `beta` will release the version `2.0.0-beta.2` on the `beta` distribution channel
|
||||
|
||||
Reference in New Issue
Block a user