semantic-release 25.0.4 → 25.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +36 -37
  2. package/bin/semantic-release.js +1 -1
  3. package/index.js +265 -37
  4. package/lib/branches/expand.js +18 -0
  5. package/lib/branches/get-tags.js +39 -0
  6. package/lib/branches/index.js +71 -0
  7. package/lib/branches/normalize.js +104 -0
  8. package/lib/definitions/branches.js +22 -0
  9. package/lib/definitions/constants.js +8 -9
  10. package/lib/definitions/errors.js +303 -0
  11. package/lib/definitions/plugins.js +108 -0
  12. package/lib/get-commits.js +31 -0
  13. package/lib/get-config.js +98 -0
  14. package/lib/get-error.js +7 -0
  15. package/lib/get-git-auth-url.js +126 -0
  16. package/lib/get-last-release.js +48 -0
  17. package/lib/get-logger.js +19 -0
  18. package/lib/get-next-version.js +35 -0
  19. package/lib/get-release-to-add.js +59 -0
  20. package/lib/git.js +381 -0
  21. package/lib/hide-sensitive.js +14 -1
  22. package/lib/plugins/index.js +103 -0
  23. package/lib/plugins/normalize.js +69 -0
  24. package/lib/plugins/pipeline.js +59 -0
  25. package/lib/plugins/utils.js +81 -0
  26. package/lib/utils.js +101 -0
  27. package/lib/verify.js +43 -0
  28. package/package.json +20 -15
  29. package/docs/README.md +0 -7
  30. package/docs/developer-guide/README.md +0 -5
  31. package/docs/developer-guide/js-api.md +0 -294
  32. package/docs/developer-guide/plugin.md +0 -284
  33. package/docs/developer-guide/shareable-configuration.md +0 -1
  34. package/docs/extending/README.md +0 -4
  35. package/docs/extending/plugins-list.md +0 -233
  36. package/docs/extending/shareable-configurations-list.md +0 -22
  37. package/docs/recipes/ci-configurations/README.md +0 -7
  38. package/docs/recipes/ci-configurations/circleci-workflows.md +0 -49
  39. package/docs/recipes/ci-configurations/github-actions.md +0 -136
  40. package/docs/recipes/ci-configurations/gitlab-ci.md +0 -98
  41. package/docs/recipes/ci-configurations/jenkins-ci.md +0 -61
  42. package/docs/recipes/ci-configurations/travis.md +0 -97
  43. package/docs/recipes/git-hosted-services/README.md +0 -3
  44. package/docs/recipes/git-hosted-services/git-auth-ssh-keys.md +0 -166
  45. package/docs/recipes/release-workflow/README.md +0 -5
  46. package/docs/recipes/release-workflow/distribution-channels.md +0 -117
  47. package/docs/recipes/release-workflow/maintenance-releases.md +0 -157
  48. package/docs/recipes/release-workflow/pre-releases.md +0 -197
  49. package/docs/support/FAQ.md +0 -253
  50. package/docs/support/README.md +0 -7
  51. package/docs/support/git-version.md +0 -4
  52. package/docs/support/node-support-policy.md +0 -21
  53. package/docs/support/node-version.md +0 -38
  54. package/docs/support/resources.md +0 -22
  55. package/docs/support/troubleshooting.md +0 -70
  56. package/docs/usage/README.md +0 -9
  57. package/docs/usage/ci-configuration.md +0 -50
  58. package/docs/usage/configuration.md +0 -206
  59. package/docs/usage/getting-started.md +0 -8
  60. package/docs/usage/installation.md +0 -51
  61. package/docs/usage/plugins.md +0 -105
  62. package/docs/usage/shareable-configurations.md +0 -7
  63. package/docs/usage/workflow-configuration.md +0 -199
@@ -1,206 +0,0 @@
1
- # Configuration
2
-
3
- **semantic-release** configuration consists of:
4
-
5
- - Git repository ([URL](#repositoryurl) and options [release branches](#branches) and [tag format](#tagformat))
6
- - Plugins [declaration](#plugins) and options
7
- - Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
8
-
9
- All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](shareable-configurations.md).
10
-
11
- Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables).
12
-
13
- ## Configuration file
14
-
15
- **semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via either:
16
-
17
- - A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.cjs`/`.mjs`
18
- - A `release.config.(js|cjs|.mjs)` file that exports an object
19
- - A `release` key in the project's `package.json` file
20
-
21
- Alternatively, some options can be set via CLI arguments.
22
-
23
- The following three examples are the same. Use main instead of master if your default branch is main.
24
-
25
- - Via `release` key in the project's `package.json` file:
26
-
27
- ```json
28
- {
29
- "release": {
30
- "branches": ["master", "next"]
31
- }
32
- }
33
- ```
34
-
35
- - Via `.releaserc` file:
36
-
37
- ```json
38
- {
39
- "branches": ["master", "next"]
40
- }
41
- ```
42
-
43
- - Via `release.config.cjs` file:
44
-
45
- ```js
46
- /**
47
- * @type {import('semantic-release').GlobalConfig}
48
- */
49
- module.exports = {
50
- branches: ["master", "next"],
51
- };
52
- ```
53
-
54
- - Via `release.config.mjs` file:
55
-
56
- ```js
57
- /**
58
- * @type {import('semantic-release').GlobalConfig}
59
- */
60
- export default {
61
- branches: ["master", "next"],
62
- };
63
- ```
64
-
65
- - Via CLI argument:
66
-
67
- ```bash
68
- $ semantic-release --branches next
69
- ```
70
-
71
- **Note**: CLI arguments take precedence over options configured in the configuration file.
72
-
73
- **Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
74
-
75
- **Note**: When configuring via `package.json`, the configuration must be under the `release` property. However, when using a `.releaserc` or a `release.config` file, the configuration must be set without a `release` property.
76
-
77
- ## Options
78
-
79
- ### extends
80
-
81
- Type: `Array`, `String`<br>
82
- CLI arguments: `-e`, `--extends`
83
-
84
- 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.
85
-
86
- **Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
87
-
88
- ### branches
89
-
90
- Type: `Array`, `String`, `Object`<br>
91
- Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`<br>
92
- CLI arguments: `--branches`
93
-
94
- The branches on which releases should happen. By default **semantic-release** will release:
95
-
96
- - regular releases to the default distribution channel from the branch `master` or `main`
97
- - 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)
98
- - regular releases to the `next` distribution channel from the branch `next` if it exists
99
- - regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
100
- - pre-releases to the `beta` distribution channel from the branch `beta` if it exists
101
- - pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists
102
-
103
- **Note**: Branches configuration key accepts [**micromatch**](https://github.com/micromatch/micromatch?tab=readme-ov-file#matching-features) globs.
104
-
105
- **Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` or `main` branch.
106
-
107
- **Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://docs.github.com/github/administering-a-repository/about-protected-branches).
108
-
109
- See [Workflow configuration](workflow-configuration.md#workflow-configuration) for more details.
110
-
111
- ### repositoryUrl
112
-
113
- Type: `String`<br>
114
- Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)<br>
115
- CLI arguments: `-r`, `--repository-url`
116
-
117
- The git repository URL.
118
-
119
- Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)).
120
-
121
- ### tagFormat
122
-
123
- Type: `String`<br>
124
- Default: `v${version}`<br>
125
- CLI arguments: `-t`, `--tag-format`
126
-
127
- 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.
128
-
129
- **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).
130
-
131
- ### plugins
132
-
133
- Type: `Array`<br>
134
- Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`<br>
135
- CLI arguments: `-p`, `--plugins`
136
-
137
- 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.
138
-
139
- Plugins configuration can defined by wrapping the name and an options object in an array.
140
-
141
- See [Plugins configuration](plugins.md#plugins) for more details.
142
-
143
- ### dryRun
144
-
145
- Type: `Boolean`<br>
146
- Default: `false` if running in a CI environment, `true` otherwise<br>
147
- CLI arguments: `-d`, `--dry-run`
148
-
149
- The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, addChannel, success and fail. In addition to this it prints the next version and release notes to the console.
150
-
151
- **Note**: The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues.
152
-
153
- ### ci
154
-
155
- Type: `Boolean`<br>
156
- Default: `true`<br>
157
- CLI arguments: `--ci` / `--no-ci`
158
-
159
- Set to `false` to skip Continuous Integration environment verifications. This allows for making releases from a local machine.
160
-
161
- **Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`.
162
-
163
- ### debug
164
-
165
- Type: `Boolean`<br>
166
- Default: `false`<br>
167
- CLI argument: `--debug`
168
-
169
- Output debugging information. This can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.
170
-
171
- **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:*')`.
172
-
173
- ## Git environment variables
174
-
175
- | Variable | Description | Default |
176
- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
177
- | `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. |
178
- | `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. |
179
- | `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. |
180
- | `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. |
181
-
182
- ## Existing version tags
183
-
184
- **semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release.
185
- 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 branches](#branches) history and is tagged with the version released, formatted according to the [tag format](#tagformat) configured (defaults to `vx.y.z`).
186
-
187
- If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.
188
-
189
- For example, if your release branch is `master`/`main`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `master`/`main` history and is tagged with `v1.1.0`.
190
-
191
- ```bash
192
- # Make sure the commit 1234567 is in the release branch history
193
- $ git branch --contains 1234567
194
-
195
- # If the commit is not in the branch history it means that either:
196
- # - you use a different branch than the one your release from before
197
- # - or the commit sha has been rewritten (with git rebase)
198
- # In both cases you need to configure your repository to have the last release commit in the history of the release branch
199
-
200
- # List the tags for the commit 1234567
201
- $ git tag --contains 1234567
202
-
203
- # If v1.1.0 is not in the list you add it with
204
- $ git tag v1.1.0 1234567
205
- $ git push origin v1.1.0
206
- ```
@@ -1,8 +0,0 @@
1
- # Getting started
2
-
3
- In order to use **semantic-release** you must follow these steps:
4
-
5
- 1. [Install](./installation.md#installation) **semantic-release** in your project
6
- 2. Configure your Continuous Integration service to [run **semantic-release**](./ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
7
- 3. Configure your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
8
- 4. Configure **semantic-release** [options and plugins](./configuration.md#configuration)
@@ -1,51 +0,0 @@
1
- # Installation
2
-
3
- ## Global installation
4
-
5
- We recommend installing **semantic-release** directly in the CI environment as part of executing with [npx](../support/FAQ.md#what-is-npx):
6
-
7
- ```sh
8
- npx semantic-release
9
- ```
10
-
11
- If you need to leverage plugins and/or presets that are not included in the base **semantic-release** package, you can install them part of executing with `npx` as well:
12
-
13
- ```sh
14
- npx --package semantic-release --package @semantic-release/exec --package conventional-changelog-conventionalcommits semantic-release
15
- ```
16
-
17
- ### Notes
18
-
19
- 1. When globally installing **semantic-release** as part of running with `npx`, we recommend setting at least the major **semantic-release** version to install.
20
- For example, by using `npx semantic-release@25`.
21
- This way you control which major version of **semantic-release** is used by your pipeline, and thus avoid breaking the release when there's a new major version of **semantic-release**.
22
- 2. Pinning **semantic-release** to an exact version makes your releases even more deterministic.
23
- But pinning also means you, or a bot, must upgrade **semantic-release** when a new version is released.
24
- 3. You can use [Renovate's regex manager](https://docs.renovatebot.com/modules/manager/regex/) to get automatic updates for **semantic-release** in either of the above scenarios.
25
- Put this in your Renovate configuration file:
26
- ```json
27
- {
28
- "customManagers": [
29
- {
30
- "customType": "regex",
31
- "description": "Update semantic-release version used by npx",
32
- "managerFilePatterns": ["^\\.github/workflows/[^/]+\\.ya?ml$"],
33
- "matchStrings": ["\\srun: npx semantic-release@(?<currentValue>.*?)\\s"],
34
- "datasourceTemplate": "npm",
35
- "depNameTemplate": "semantic-release"
36
- }
37
- ]
38
- }
39
- ```
40
- 4. `npx` is a tool bundled with `npm@>=5.2.0`. You can use it to install (and run) the **semantic-release** binary.
41
- See [What is npx](../support/FAQ.md#what-is-npx) for more details.
42
-
43
- ## Local installation
44
-
45
- Since **semantic-release** isn't truly a development dependency, but rather a release dependency, we recommend avoiding installation as a local dependency of your project.
46
- Instead, we recommend installing it globally in your CI environment as part of executing with [npx](../support/FAQ.md#what-is-npx) as described [above](#global-insallation).
47
- Installing only during the release process avoids:
48
-
49
- - installing unnecessary dependencies during development and testing, including the fairly sizable dependency on **npm**
50
- - installing a different version of **npm** into `node_modules/` than the one used to run the release, which can lead to conflicts and unexpected behavior
51
- - installing dependencies that could conflict with other development dependencies, like **commitlint**
@@ -1,105 +0,0 @@
1
- # Plugins
2
-
3
- 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.
4
-
5
- A plugin is a npm module that can implement one or more of the following steps:
6
-
7
- | Step | Required | Description |
8
- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
- | `verifyConditions` | No | Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc... |
10
- | `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. |
11
- | `verifyRelease` | No | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published. |
12
- | `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. |
13
- | `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. |
14
- | `publish` | No | Responsible for publishing the release. |
15
- | `addChannel` | No | Responsible for adding a release channel (e.g. adding an npm dist-tag to a release). |
16
- | `success` | No | Responsible for notifying of a new release. |
17
- | `fail` | No | Responsible for notifying of a failed release. |
18
-
19
- Release steps will run in that order. At each step, **semantic-release** will run every plugin in the [`plugins` array](#plugins-declaration-and-execution-order), as long as the plugin implements the step.
20
-
21
- **Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used.
22
-
23
- ## Plugins installation
24
-
25
- ### Default plugins
26
-
27
- These four plugins are already part of **semantic-release** and are listed in order of execution. They do not have to be installed separately:
28
-
29
- ```
30
- "@semantic-release/commit-analyzer"
31
- "@semantic-release/release-notes-generator"
32
- "@semantic-release/npm"
33
- "@semantic-release/github"
34
- ```
35
-
36
- ### Additional plugins
37
-
38
- [Additional plugins](../extending/plugins-list.md) have to be installed via npm:
39
-
40
- ```bash
41
- $ npm install @semantic-release/git @semantic-release/changelog -D
42
- ```
43
-
44
- ## Plugins declaration and execution order
45
-
46
- Each plugin must be configured with the [`plugins` options](./configuration.md#plugins) by specifying the list of plugins by npm module name.
47
-
48
- ```json
49
- {
50
- "plugins": ["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm"]
51
- }
52
- ```
53
-
54
- **Note:** If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it.
55
-
56
- 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.
57
-
58
- ```json
59
- {
60
- "plugins": [
61
- "@semantic-release/commit-analyzer",
62
- "@semantic-release/release-notes-generator",
63
- "@semantic-release/npm",
64
- "@semantic-release/git"
65
- ]
66
- }
67
- ```
68
-
69
- With this configuration **semantic-release** will:
70
-
71
- - execute the `verifyConditions` implementation of `@semantic-release/npm` then `@semantic-release/git`
72
- - execute the `analyzeCommits` implementation of `@semantic-release/commit-analyzer`
73
- - execute the `generateNotes` implementation of `@semantic-release/release-notes-generator`
74
- - execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git`
75
- - execute the `publish` implementation of `@semantic-release/npm`
76
-
77
- Order is first determined by release steps (such as `verifyConditions` → `analyzeCommits`). At each release step, plugins are executed in the order in which they are defined.
78
-
79
- ## Plugin options configuration
80
-
81
- A plugin configuration can be specified by wrapping the name and an options object in an array. Options configured this way will be passed only to that specific plugin.
82
-
83
- Global plugin configuration can be defined at the root of the **semantic-release** configuration object. Options configured this way will be passed to all plugins.
84
-
85
- ```json
86
- {
87
- "plugins": [
88
- "@semantic-release/commit-analyzer",
89
- "@semantic-release/release-notes-generator",
90
- [
91
- "@semantic-release/github",
92
- {
93
- "assets": ["dist/**"]
94
- }
95
- ],
96
- "@semantic-release/git"
97
- ],
98
- "preset": "angular"
99
- }
100
- ```
101
-
102
- With this configuration:
103
-
104
- - 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`)
105
- - 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,7 +0,0 @@
1
- # Shareable configurations
2
-
3
- A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects.
4
-
5
- The shareable configurations to use can be set with the [extends](configuration.md#extends) option.
6
-
7
- See [shareable configurations list](../extending/shareable-configurations-list.md).
@@ -1,199 +0,0 @@
1
- # Release Workflow configuration
2
-
3
- **semantic-release** enables managing and automating complex release workflow, based on multiple Git branches and distribution channels.
4
- This enables:
5
-
6
- - Distributing certain releases to a particular group of users via distribution channels
7
- - Managing the availability of releases on distribution channels via branches merge
8
- - Maintaining multiple lines of releases in parallel
9
- - Working on large future releases outside the normal flow of one version increment per Git push
10
-
11
- See [Release workflow recipes](../recipes/release-workflow/README.md#release-workflow) for detailed examples.
12
-
13
- The release workflow is configured via the [branches option](./configuration.md#branches) which accepts a single or an array of branch definitions.
14
- 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.
15
-
16
- A branch can be defined as one of three types:
17
-
18
- - [release](#release-branches): to make releases on top of the last version released
19
- - [maintenance](#maintenance-branches): to make releases on top of an old release
20
- - [pre-release](#pre-release-branches): to make pre-releases
21
-
22
- The type of the branch is automatically determined based on naming convention and/or [properties](#branches-properties).
23
-
24
- ## Branches properties
25
-
26
- | Property | Branch type | Description | Default |
27
- | ------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
28
- | `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. |
29
- | `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. |
30
- | `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`. |
31
- | `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release denotation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease). | - |
32
-
33
- ### name
34
-
35
- A `name` is required for any type of branch.
36
- It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-features) in which case the definition will be expanded to one per matching branch existing in the repository.
37
-
38
- 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.
39
-
40
- For example the configuration `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next']` will be expanded as:
41
-
42
- ```js
43
- {
44
- branches: [
45
- { name: "1.x", range: "1.x", channel: "1.x" }, // Only after the `1.x` is created in the repo
46
- { name: "2.x", range: "2.x", channel: "2.x" }, // Only after the `2.x` is created in the repo
47
- { name: "master" },
48
- { name: "next", channel: "next" }, // Only after the `next` is created in the repo
49
- ];
50
- }
51
- ```
52
-
53
- ### channel
54
-
55
- The `channel` can be defined for any branch type. By default releases will be done on the default distribution channel (for example the `@latest` [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm) for the first [release branch](#release-branches) and on a distribution channel named based on the branch `name` for any other branch.
56
- If the `channel` property is set to `false` the default channel will be used.
57
-
58
- The value of `channel`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
59
-
60
- For example the configuration `['master', {name: 'next', channel: 'channel-${name}'}]` will be expanded as:
61
-
62
- ```js
63
- {
64
- branches: [
65
- { name: "master" }, // `channel` is undefined so the default distribution channel will be used
66
- { name: "next", channel: "channel-next" }, // `channel` is built with the template `channel-${name}`
67
- ];
68
- }
69
- ```
70
-
71
- ### range
72
-
73
- 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`.
74
-
75
- For example the configuration `['1.1.x', '1.2.x', 'master']` will be expanded as:
76
-
77
- ```js
78
- {
79
- branches: [
80
- { name: "1.1.x", range: "1.1.x", channel: "1.1.x" },
81
- { name: "1.2.x", range: "1.2.x", channel: "1.2.x" },
82
- { name: "master" },
83
- ];
84
- }
85
- ```
86
-
87
- ### prerelease
88
-
89
- A `prerelease` property applies only to pre-release branches and the `prerelease` value must be valid per the [Semantic Versioning Specification](https://semver.org/#spec-item-9). It will determine the name of versions (for example if `prerelease` is set to `beta` the version be formatted like `2.0.0-beta.1`, `2.0.0-beta.2` etc...).
90
- If the `prerelease` property is set to `true` the `name` value will be used.
91
-
92
- The value of `prerelease`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available.
93
-
94
- For example the configuration `['master', {name: 'pre/rc', prerelease: '${name.replace(/^pre\\//g, "")}'}, {name: 'beta', prerelease: true}]` will be expanded as:
95
-
96
- ```js
97
- {
98
- branches: [
99
- { name: "master" },
100
- { name: "pre/rc", channel: "pre/rc", prerelease: "rc" }, // `prerelease` is built with the template `${name.replace(/^pre\\//g, "")}`
101
- { name: "beta", channel: "beta", prerelease: true }, // `prerelease` is set to `beta` as it is the value of `name`
102
- ];
103
- }
104
- ```
105
-
106
- ## Branch types
107
-
108
- ### Release branches
109
-
110
- A release branch is the base type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org), optionally on a specific distribution channel. Distribution channels (for example [npm dist-tags](https://docs.npmjs.com/cli/dist-tag) or [Chrome release channels](https://www.chromium.org/getting-involved/dev-channel)) are a way to distribute new releases only to a subset of users in order to get early feedback. Later on, those releases can be added to the general distribution channel to be made available to all users.
111
-
112
- **semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release branch to another](#merging-into-a-release-branch).
113
-
114
- A project must define a minimum of 1 release branch and can have a maximum of 3. The order of the release branch definitions is significant, as versions released on a given branch must always be higher than the last release made on the previous branch. This allow to avoid situation that would lead to an attempt to publish releases with the same version number but different codebase. When multiple release branches are configured and a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them.
115
-
116
- **Note:** With **semantic-release** as with most package managers, a release version must be unique, independently of the distribution channel on which it is available.
117
-
118
- See [publishing on distribution channels recipe](../recipes/release-workflow/distribution-channels.md) for a detailed example.
119
-
120
- #### Pushing to a release branch
121
-
122
- 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:
123
-
124
- - Only versions in range `1.x.x` can be published from `master`, so only `fix` and `feat` commits can be pushed to `master`
125
- - 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
126
-
127
- This verification prevent scenario such as:
128
-
129
- 1. Create a `feat` commit on `next` which triggers the release of version `1.0.0` on the `next` channel
130
- 2. Merge `next` into `master` which adds `1.0.0` on the default channel
131
- 3. Create a `feat` commit on `next` which triggers the release of version `1.1.0` on the `next` channel
132
- 4. Create a `feat` commit on `master` which would attempt to release the version `1.1.0` on the default channel
133
-
134
- In step 4 **semantic-release** will throw an `EINVALIDNEXTVERSION` error to prevent the attempt at releasing version `1.1.0` which was already released on step 3 with a different codebase. The error will indicate that the commit should be created on `next` instead. Alternatively if the `next` branch is merged into `master`, the version `1.1.0` will be made available on the default channel and the `feat` commit would be allowed on `master` to release `1.2.0`.
135
-
136
- #### Merging into a release branch
137
-
138
- When merging commits associated with a release from one release branch to another, **semantic-release** will make the corresponding version available on the channel associated with the target branch.
139
-
140
- When merging commits not associated with a release, commits from a [maintenance branch](#maintenance-branches) or commits from a [pre-release branch](#pre-release-branches) **semantic-release** will treat them as [pushed commits](#pushing-to-a-release-branch) and publish a new release if necessary.
141
-
142
- ### Maintenance branches
143
-
144
- A maintenance branch is a type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org) on top of the codebase of an old release. This is useful when you need to provide fixes or features to users who cannot upgrade to the last version of your package.
145
-
146
- A maintenance branch is characterized by a range which defines the versions that can be published from it. The [`range`](#range) value of each maintenance branch must be unique across the project.
147
-
148
- **semantic-release** will always publish releases to a distribution channel specific to the range, so only the users who choose to use that particular line of versions will receive new releases.
149
-
150
- Maintenance branches are always considered lower than [release branches](#release-branches) and similarly to them, when a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them.
151
-
152
- **semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release or maintenance branch to another maintenance branch](#merging-into-a-maintenance-branch), however only versions within the branch `range` can be merged. If a merged version is outside the maintenance branch `range`, **semantic-release** will not add to the corresponding channel and will throw an `EINVALIDMAINTENANCEMERGE` error.
153
-
154
- See [publishing maintenance releases recipe](../recipes/release-workflow/maintenance-releases.md) for a detailed example.
155
-
156
- #### Pushing to a maintenance branch
157
-
158
- With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.5.0` then:
159
-
160
- - 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`
161
- - 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`
162
- - 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`
163
-
164
- #### Merging into a maintenance branch
165
-
166
- With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.0.0` then:
167
-
168
- - Creating the branch `1.0.x` from `master` will make the `1.0.0` release available on the `1.0.x` distribution channel
169
- - Pushing a `fix` commit on the `1.0.x` branch will release the version `1.0.1` on the `1.0.x` distribution channel
170
- - Creating the branch `1.x` from `master` will make the `1.0.0` release available on the `1.x` distribution channel
171
- - Merging the branch `1.0.x` into `1.x` will make the version `1.0.1` available on the `1.x` distribution channel
172
-
173
- ### Pre-release branches
174
-
175
- A pre-release branch is a type of branch used by **semantic-release** that allows to publish releases with a [pre-release version](https://semver.org/#spec-item-9).
176
- Using a pre-release version allow to publish multiple releases with the same version. Those release will be differentiated via their identifiers (in `1.0.0-alpha.1` the identifier is `alpha.1`).
177
- This is useful when you need to work on a future major release that will include many breaking changes but you do not want to increment the version number for each breaking change commit.
178
-
179
- A pre-release branch is characterized by the `prerelease` property that defines the static part of the version released (in `1.0.0-alpha.1` the static part fo the identifier is `alpha`). The [`prerelease`](#prerelease) value of each pre-release branch must be unique across the project.
180
-
181
- **semantic-release** will always publish pre-releases to a specific distribution channel, so only the users who choose to use that particular line of versions will receive new releases.
182
-
183
- When merging commits associated with an existing release, **semantic-release** will treat them as [pushed commits](#pushing-to-a-pre-release-branch) and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch.
184
-
185
- See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md) for a detailed example.
186
-
187
- #### Pushing to a pre-release branch
188
-
189
- With the configuration `"branches": ["master", {"name": "beta", "prerelease": true}]`, if the last release published from `master` is `1.0.0` then:
190
-
191
- - Pushing a `BREAKING CHANGE` commit on the `beta` branch will release the version `2.0.0-beta.1` on the `beta` distribution channel
192
- - 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
193
-
194
- #### Merging into a pre-release branch
195
-
196
- 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:
197
-
198
- - Pushing a `fix` commit on the `master` branch will release the version `1.0.1` on the default distribution channel
199
- - Merging the branch `master` into `beta` will release the version `2.0.0-beta.2` on the `beta` distribution channel