semantic-release 15.13.20 → 15.13.24
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.
- package/README.md +35 -39
- package/docs/README.md +5 -5
- package/docs/{04-developer-guide → developer-guide}/README.md +0 -0
- package/docs/{04-developer-guide → developer-guide}/js-api.md +3 -3
- package/docs/{04-developer-guide → developer-guide}/plugin.md +0 -0
- package/docs/{04-developer-guide → developer-guide}/shareable-configuration.md +0 -0
- package/docs/{02-extending → extending}/README.md +0 -0
- package/docs/{02-extending → extending}/plugins-list.md +0 -0
- package/docs/{02-extending → extending}/shareable-configurations-list.md +0 -0
- package/docs/recipes/README.md +11 -0
- package/docs/{03-recipes → recipes}/circleci-workflows.md +4 -4
- package/docs/{03-recipes → recipes}/git-auth-ssh-keys.md +1 -1
- package/docs/{03-recipes → recipes}/gitlab-ci.md +4 -4
- package/docs/{03-recipes → recipes}/travis.md +6 -6
- package/docs/{05-support → support}/FAQ.md +19 -19
- package/docs/{05-support → support}/README.md +0 -0
- package/docs/{05-support → support}/node-support-policy.md +0 -0
- package/docs/{05-support → support}/node-version.md +1 -1
- package/docs/{05-support → support}/resources.md +0 -0
- package/docs/{05-support → support}/troubleshooting.md +0 -0
- package/docs/{01-usage → usage}/README.md +0 -0
- package/docs/{01-usage → usage}/ci-configuration.md +15 -21
- package/docs/{01-usage → usage}/configuration.md +50 -133
- package/docs/usage/getting-started.md +22 -0
- package/docs/usage/installation.md +29 -0
- package/docs/{01-usage → usage}/plugins.md +28 -22
- package/docs/usage/shareable-configurations.md +7 -0
- package/package.json +3 -11
- package/docs/01-usage/getting-started.md +0 -32
- package/docs/01-usage/installation.md +0 -22
- package/docs/01-usage/shareable-configurations.md +0 -7
- package/docs/03-recipes/README.md +0 -3
- package/docs/03-recipes/ci-pipelines-recipes.md +0 -4
- package/docs/03-recipes/git-hosted-services.md +0 -2
- package/docs/03-recipes/package-managers-and-languages.md +0 -2
package/README.md
CHANGED
|
@@ -39,10 +39,10 @@ This removes the immediate connection between human emotions and version numbers
|
|
|
39
39
|
- New features and fixes are immediately available to users
|
|
40
40
|
- Notify maintainers and users of new releases
|
|
41
41
|
- Use formalized commit message convention to document changes in the codebase
|
|
42
|
-
- Integrate with your [continuous integration workflow](docs/
|
|
42
|
+
- Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
|
|
43
43
|
- Avoid potential errors associated with manual releases
|
|
44
|
-
- Support any [package managers and languages](docs/
|
|
45
|
-
- Simple and reusable configuration via [shareable configurations](docs/
|
|
44
|
+
- Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
|
|
45
|
+
- Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
|
|
46
46
|
|
|
47
47
|
## How does it work?
|
|
48
48
|
|
|
@@ -50,7 +50,7 @@ This removes the immediate connection between human emotions and version numbers
|
|
|
50
50
|
|
|
51
51
|
**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.
|
|
52
52
|
|
|
53
|
-
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/
|
|
53
|
+
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.
|
|
54
54
|
|
|
55
55
|
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.
|
|
56
56
|
|
|
@@ -71,55 +71,51 @@ Here is an example of the release type that will be done based on a commit messa
|
|
|
71
71
|
For each new commits added to the release branch (i.e. `master`) with `git push` or by merging a pull request or merging from another branch, a CI build is triggered and runs the `semantic-release` command to make a release if there are codebase changes since the last release that affect the package functionalities.
|
|
72
72
|
|
|
73
73
|
If you need more control over the timing of releases you have a couple of options:
|
|
74
|
-
- Publish releases on a distribution channel (for example npm’s [dist-tags](https://docs.npmjs.com/cli/dist-tag)). This way you can keep control over what your users end up using by default, and you can decide when to make an automatically released version available to the stable channel, and promote it.
|
|
74
|
+
- Publish releases on a distribution channel (for example npm’s [dist-tags](https://docs.npmjs.com/cli/dist-tag)). This way you can keep control over what your users end up using by default, and you can decide when to make an automatically released version available to the stable channel, and promote it.
|
|
75
75
|
- Develop on a `dev` branch and merge it to the release branch (i.e. `master`) once you are ready to publish. **semantic-release** will run only on pushes to the release branch.
|
|
76
76
|
|
|
77
77
|
### Release steps
|
|
78
78
|
|
|
79
79
|
After running the tests, the command `semantic-release` will execute the following steps:
|
|
80
80
|
|
|
81
|
-
| Step |
|
|
82
|
-
|
|
83
|
-
| Verify Conditions |
|
|
84
|
-
| Get last release |
|
|
85
|
-
| Analyze commits |
|
|
86
|
-
| Verify release |
|
|
87
|
-
| Generate notes |
|
|
88
|
-
| Create Git tag |
|
|
89
|
-
| Prepare |
|
|
90
|
-
| Publish |
|
|
91
|
-
| Notify |
|
|
81
|
+
| Step | Description |
|
|
82
|
+
|-------------------|---------------------------------------------------------------------------------------------------------------------------------|
|
|
83
|
+
| Verify Conditions | Verify all the conditions to proceed with the release. |
|
|
84
|
+
| 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). |
|
|
85
|
+
| Analyze commits | Determine the type of release based on the commits added since the last release. |
|
|
86
|
+
| Verify release | Verify the release conformity. |
|
|
87
|
+
| Generate notes | Generate release notes for the commits added since the last release. |
|
|
88
|
+
| Create Git tag | Create a Git tag corresponding to the new release version. |
|
|
89
|
+
| Prepare | Prepare the release. |
|
|
90
|
+
| Publish | Publish the release. |
|
|
91
|
+
| Notify | Notify of new releases or errors. |
|
|
92
92
|
|
|
93
93
|
## Documentation
|
|
94
94
|
|
|
95
95
|
- Usage
|
|
96
|
-
- [Getting started](docs/
|
|
97
|
-
- [Installation](docs/
|
|
98
|
-
- [CI Configuration](docs/
|
|
99
|
-
- [Configuration](docs/
|
|
100
|
-
- [Plugins](docs/
|
|
101
|
-
- [Shareable configurations](docs/
|
|
96
|
+
- [Getting started](docs/usage/getting-started.md#getting-started)
|
|
97
|
+
- [Installation](docs/usage/installation.md#installation)
|
|
98
|
+
- [CI Configuration](docs/usage/ci-configuration.md#ci-configuration)
|
|
99
|
+
- [Configuration](docs/usage/configuration.md#configuration)
|
|
100
|
+
- [Plugins](docs/usage/plugins.md)
|
|
101
|
+
- [Shareable configurations](docs/usage/shareable-configurations.md)
|
|
102
102
|
- Extending
|
|
103
|
-
- [
|
|
104
|
-
- [
|
|
103
|
+
- [Plugins](docs/extending/plugins-list.md)
|
|
104
|
+
- [Shareable configuration](docs/extending/shareable-configurations-list.md)
|
|
105
105
|
- Recipes
|
|
106
|
-
- [CI
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
- [GitLab CI](docs/03-recipes/gitlab-ci.md)
|
|
110
|
-
- [Git hosted services](docs/03-recipes/git-hosted-services.md)
|
|
111
|
-
- [Git authentication with SSH keys](docs/03-recipes/git-auth-ssh-keys.md)
|
|
112
|
-
- [Package managers and languages](docs/03-recipes/package-managers-and-languages.md)
|
|
106
|
+
- [CI configurations](docs/recipes/README.md#ci-configurations)
|
|
107
|
+
- [Git hosted services](docs/recipes/README.md#git-hosted-services)
|
|
108
|
+
- [Package managers and languages](docs/recipes/README.md#package-managers-and-languages)
|
|
113
109
|
- Developer guide
|
|
114
|
-
- [JavaScript API](docs/
|
|
115
|
-
- [
|
|
116
|
-
- [Shareable configuration development](docs/
|
|
110
|
+
- [JavaScript API](docs/developer-guide/js-api.md)
|
|
111
|
+
- [Plugins development](docs/developer-guide/plugin.md)
|
|
112
|
+
- [Shareable configuration development](docs/developer-guide/shareable-configuration.md)
|
|
117
113
|
- Support
|
|
118
|
-
- [Resources](docs/
|
|
119
|
-
- [Frequently Asked Questions](docs/
|
|
120
|
-
- [Troubleshooting](docs/
|
|
121
|
-
- [Node version requirement](docs/
|
|
122
|
-
- [Node Support Policy](docs/
|
|
114
|
+
- [Resources](docs/support/resources.md)
|
|
115
|
+
- [Frequently Asked Questions](docs/support/FAQ.md)
|
|
116
|
+
- [Troubleshooting](docs/support/troubleshooting.md)
|
|
117
|
+
- [Node version requirement](docs/support/node-version.md)
|
|
118
|
+
- [Node Support Policy](docs/support/node-support-policy.md)
|
|
123
119
|
|
|
124
120
|
## Get help
|
|
125
121
|
|
package/docs/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# semantic-release documentation
|
|
2
2
|
|
|
3
|
-
- [Usage](
|
|
4
|
-
- [Extending](
|
|
5
|
-
- [Recipes](
|
|
6
|
-
- [Developer Guide](
|
|
7
|
-
- [Support](
|
|
3
|
+
- [Usage](usage/README.md) - **semantic-release** installation and configuration
|
|
4
|
+
- [Extending](extending/README.md)- Extending **semantic-release** with plugins and shareable configurations
|
|
5
|
+
- [Recipes](recipes/README.md) - Community written recipes for common **semantic-release** use-cases
|
|
6
|
+
- [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
|
|
7
|
+
- [Support](support/README.md) - FAQ and troubleshooting
|
|
File without changes
|
|
@@ -65,9 +65,9 @@ Type: `Object`
|
|
|
65
65
|
|
|
66
66
|
**semantic-release** options.
|
|
67
67
|
|
|
68
|
-
Can be used to set any [core option](../
|
|
68
|
+
Can be used to set any [core option](../usage/configuration.md#configuration) or [plugin options](../usage/plugins.md#configuration).
|
|
69
69
|
|
|
70
|
-
Each option, will take precedence over options configured in the [configuration file](../
|
|
70
|
+
Each option, will take precedence over options configured in the [configuration file](../usage/configuration.md#configuration) and [shareable configurations](../usage/configuration.md#extends).
|
|
71
71
|
|
|
72
72
|
#### config
|
|
73
73
|
|
|
@@ -229,7 +229,7 @@ Example:
|
|
|
229
229
|
|
|
230
230
|
Type: `Array<Object>`
|
|
231
231
|
|
|
232
|
-
The list of releases published, one release per [publish plugin](../
|
|
232
|
+
The list of releases published, one release per [publish plugin](../usage/plugins.md#publish-plugin).<br>
|
|
233
233
|
Each release object has the following properties:
|
|
234
234
|
|
|
235
235
|
| Name | Type | Description |
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Recipes
|
|
2
|
+
|
|
3
|
+
## CI configurations
|
|
4
|
+
- [CircleCI 2.0 workflows](circleci-workflows.md)
|
|
5
|
+
- [Travis CI](travis.md)
|
|
6
|
+
- [GitLab CI](gitlab-ci.md)
|
|
7
|
+
|
|
8
|
+
## Git hosted services
|
|
9
|
+
- [Git authentication with SSH keys](git-auth-ssh-keys.md)
|
|
10
|
+
|
|
11
|
+
## Package managers and languages
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
## Environment variables
|
|
4
4
|
|
|
5
|
-
The [Authentication](../
|
|
5
|
+
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)..
|
|
6
6
|
|
|
7
|
-
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../
|
|
7
|
+
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
|
|
8
8
|
|
|
9
9
|
## Multiple Node jobs configuration
|
|
10
10
|
|
|
@@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
|
|
|
12
12
|
|
|
13
13
|
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.
|
|
14
14
|
|
|
15
|
-
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](../
|
|
15
|
+
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).
|
|
16
16
|
|
|
17
17
|
```yaml
|
|
18
18
|
version: 2
|
|
@@ -54,7 +54,7 @@ workflows:
|
|
|
54
54
|
|
|
55
55
|
### `package.json` configuration for multiple Node jobs
|
|
56
56
|
|
|
57
|
-
A `package.json` is required only for [local](../
|
|
57
|
+
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
|
58
58
|
|
|
59
59
|
```json
|
|
60
60
|
{
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Git authentication with SSH keys
|
|
2
2
|
|
|
3
|
-
When using [environment variables](../
|
|
3
|
+
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).
|
|
4
4
|
|
|
5
5
|
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.
|
|
6
6
|
|
|
@@ -2,19 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
## Environment variables
|
|
4
4
|
|
|
5
|
-
The [Authentication](../
|
|
5
|
+
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).
|
|
6
6
|
|
|
7
7
|
## Node project configuration
|
|
8
8
|
|
|
9
9
|
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.
|
|
10
10
|
|
|
11
|
-
**Note**: The publish pipeline must run a [Node >= 8 version](../
|
|
11
|
+
**Note**: The publish pipeline must run a [Node >= 8 version](../support/FAQ.md#why-does-semantic-release-require-node-version--83).
|
|
12
12
|
|
|
13
13
|
### `.gitlab-ci.yml` configuration for Node projects
|
|
14
14
|
|
|
15
15
|
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.
|
|
16
16
|
|
|
17
|
-
**Note**: The`semantic-release` execution command varies depending if you are using a [local](../
|
|
17
|
+
**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.
|
|
18
18
|
|
|
19
19
|
```yaml
|
|
20
20
|
# The release pipeline will run only if all jobs in the test pipeline are successful
|
|
@@ -46,7 +46,7 @@ publish:
|
|
|
46
46
|
|
|
47
47
|
### `package.json` configuration
|
|
48
48
|
|
|
49
|
-
A `package.json` is required only for [local](../
|
|
49
|
+
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
|
50
50
|
|
|
51
51
|
```json
|
|
52
52
|
{
|
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
## Environment variables
|
|
4
4
|
|
|
5
|
-
The [Authentication](../
|
|
5
|
+
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).
|
|
6
6
|
|
|
7
|
-
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../
|
|
7
|
+
Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
|
|
8
8
|
|
|
9
9
|
## Node.js projects configuration
|
|
10
10
|
|
|
@@ -12,7 +12,7 @@ Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with
|
|
|
12
12
|
|
|
13
13
|
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.
|
|
14
14
|
|
|
15
|
-
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](../
|
|
15
|
+
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).
|
|
16
16
|
|
|
17
17
|
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.
|
|
18
18
|
|
|
@@ -43,7 +43,7 @@ jobs:
|
|
|
43
43
|
|
|
44
44
|
### `package.json` configuration for multiple Node jobs
|
|
45
45
|
|
|
46
|
-
A `package.json` is required only for [local](../
|
|
46
|
+
A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
|
|
47
47
|
|
|
48
48
|
```json
|
|
49
49
|
{
|
|
@@ -57,13 +57,13 @@ A `package.json` is required only for [local](../01-usage/installation.md#local-
|
|
|
57
57
|
|
|
58
58
|
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).
|
|
59
59
|
|
|
60
|
-
This recipe cover the Travis specifics only. See [Non JavaScript projects recipe](../
|
|
60
|
+
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.
|
|
61
61
|
|
|
62
62
|
### `.travis.yml` configuration for non-JavaScript projects
|
|
63
63
|
|
|
64
64
|
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.
|
|
65
65
|
|
|
66
|
-
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](../
|
|
66
|
+
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).
|
|
67
67
|
|
|
68
68
|
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.
|
|
69
69
|
|
|
@@ -34,11 +34,11 @@ If using npm hook scripts is not possible, and alternative solution is to [`@sem
|
|
|
34
34
|
|
|
35
35
|
## Is there a way to preview which version would currently get published?
|
|
36
36
|
|
|
37
|
-
Yes with the [dry-run options](../
|
|
37
|
+
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.
|
|
38
38
|
|
|
39
39
|
## Can I use semantic-release with Yarn?
|
|
40
40
|
|
|
41
|
-
If you are using a [local](../
|
|
41
|
+
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.
|
|
42
42
|
|
|
43
43
|
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:
|
|
44
44
|
|
|
@@ -48,7 +48,7 @@ $ yarn install --ignore-engines
|
|
|
48
48
|
|
|
49
49
|
**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`.
|
|
50
50
|
|
|
51
|
-
Alternatively you can use a [global](../
|
|
51
|
+
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.
|
|
52
52
|
|
|
53
53
|
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:
|
|
54
54
|
|
|
@@ -56,14 +56,14 @@ If your CI environment provides [nvm](https://github.com/creationix/nvm) you can
|
|
|
56
56
|
$ nvm install 8 && yarn global add semantic-release && semantic-release
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
-
See the [CI
|
|
59
|
+
See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
|
|
60
60
|
|
|
61
61
|
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.
|
|
62
62
|
|
|
63
|
-
For [local installation](../
|
|
63
|
+
For [local installation](../usage/installation.md#local-installation) replace
|
|
64
64
|
`npx semantic-release` with `yarn run semantic-release`.
|
|
65
65
|
|
|
66
|
-
For [global installation](../
|
|
66
|
+
For [global installation](../usage/installation.md#global-installation) replace
|
|
67
67
|
`npx semantic-release` with `yarn global add semantic-release && semantic-release`.
|
|
68
68
|
|
|
69
69
|
## Can I use semantic-release to publish non-JavaScript packages?
|
|
@@ -71,13 +71,13 @@ For [global installation](../01-usage/installation.md#global-installation) repla
|
|
|
71
71
|
Yes, **semantic-release** is a Node CLI application but it can be used to publish any type of packages.
|
|
72
72
|
|
|
73
73
|
To publish a non-Node package (without a `package.json`) you would need to:
|
|
74
|
-
- Use a [global](../
|
|
75
|
-
- Set **semantic-release** [options](../
|
|
74
|
+
- Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
|
|
75
|
+
- Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or rc file](../usage/configuration.md#configuration)
|
|
76
76
|
- 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
|
|
77
77
|
|
|
78
|
-
See the [CI
|
|
78
|
+
See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
|
|
79
79
|
|
|
80
|
-
In addition you will need to configure the **semantic-release** [plugins](../
|
|
80
|
+
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.
|
|
81
81
|
|
|
82
82
|
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.
|
|
83
83
|
|
|
@@ -99,19 +99,19 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti
|
|
|
99
99
|
|
|
100
100
|
**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.
|
|
101
101
|
|
|
102
|
-
See the [package managers and languages recipes](../
|
|
102
|
+
See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types.
|
|
103
103
|
|
|
104
104
|
## Can I use semantic-release with any CI service?
|
|
105
105
|
|
|
106
106
|
Yes, **semantic-release** can be used with any CI service, as long as it provides:
|
|
107
|
-
- A way to set [authentication](../
|
|
108
|
-
- 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](../
|
|
107
|
+
- A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
|
|
108
|
+
- 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)
|
|
109
109
|
|
|
110
|
-
See the [CI
|
|
110
|
+
See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
|
|
111
111
|
|
|
112
112
|
## Can I run semantic-release on my local machine rather than on a CI server?
|
|
113
113
|
|
|
114
|
-
Yes, you can by explicitly setting the [`--no-ci` CLI option](../
|
|
114
|
+
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:
|
|
115
115
|
|
|
116
116
|
```bash
|
|
117
117
|
$ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci
|
|
@@ -123,11 +123,11 @@ However this is not the recommended approach, as running unit and integration te
|
|
|
123
123
|
|
|
124
124
|
Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
|
|
125
125
|
|
|
126
|
-
See the [GitLab CI recipes](../
|
|
126
|
+
See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
|
|
127
127
|
|
|
128
128
|
## Can I use semantic-release with any Git hosted environment?
|
|
129
129
|
|
|
130
|
-
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](../
|
|
130
|
+
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).
|
|
131
131
|
|
|
132
132
|
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.
|
|
133
133
|
|
|
@@ -230,13 +230,13 @@ See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/i
|
|
|
230
230
|
|
|
231
231
|
**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).
|
|
232
232
|
|
|
233
|
-
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](../
|
|
233
|
+
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).
|
|
234
234
|
|
|
235
235
|
## Why does semantic-release require Node version >= 8.3?
|
|
236
236
|
|
|
237
237
|
**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**.
|
|
238
238
|
|
|
239
|
-
See [Node version requirement](
|
|
239
|
+
See [Node version requirement](./node-version.md#node-version-requirement) for more details and solutions.
|
|
240
240
|
|
|
241
241
|
## What is npx?
|
|
242
242
|
|
|
File without changes
|
|
File without changes
|
|
@@ -12,7 +12,7 @@ See our [Node Support Policy](node-support-policy.md) for our long-term promise
|
|
|
12
12
|
|
|
13
13
|
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.
|
|
14
14
|
|
|
15
|
-
See [CI configuration](../
|
|
15
|
+
See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
|
|
16
16
|
|
|
17
17
|
## Alternative solutions
|
|
18
18
|
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
@@ -1,12 +1,9 @@
|
|
|
1
1
|
# CI configuration
|
|
2
2
|
|
|
3
|
-
##
|
|
3
|
+
## Run `semantic-release` only after all tests succeeded
|
|
4
4
|
|
|
5
|
-
The `semantic-release` command
|
|
6
|
-
|
|
7
|
-
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.
|
|
8
|
-
|
|
9
|
-
Follow the CI system's documentation to find out how to do this:
|
|
5
|
+
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.
|
|
6
|
+
Here is a few example of the CI services that can be used to achieve this:
|
|
10
7
|
- [Travis Build Stages](https://docs.travis-ci.com/user/build-stages)
|
|
11
8
|
- [CircleCI Workflows](https://circleci.com/docs/2.0/workflows)
|
|
12
9
|
- [Codeship Deployment Pipelines](https://documentation.codeship.com/basic/builds-and-configuration/deployment-pipelines)
|
|
@@ -15,15 +12,13 @@ Follow the CI system's documentation to find out how to do this:
|
|
|
15
12
|
- [Wercker Workflows](http://devcenter.wercker.com/docs/workflows)
|
|
16
13
|
- [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
|
|
19
16
|
|
|
20
17
|
## Authentication
|
|
21
18
|
|
|
22
|
-
### Push access to remote
|
|
23
|
-
|
|
24
|
-
**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.
|
|
19
|
+
### Push access to the remote repository
|
|
25
20
|
|
|
26
|
-
The Git authentication can be set with one of the following environment variables:
|
|
21
|
+
**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:
|
|
27
22
|
|
|
28
23
|
| Variable | Description |
|
|
29
24
|
|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
@@ -32,22 +27,21 @@ The Git authentication can be set with one of the following environment variable
|
|
|
32
27
|
| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). |
|
|
33
28
|
| `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. |
|
|
34
29
|
|
|
35
|
-
Alternatively the Git authentication
|
|
36
|
-
|
|
37
|
-
### Authentication needs for plugins
|
|
30
|
+
Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-auth-ssh-keys.md).
|
|
38
31
|
|
|
39
|
-
|
|
32
|
+
### Authentication for plugins
|
|
40
33
|
|
|
41
|
-
|
|
42
|
-
- The default [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugin requires the same `GH_TOKEN` environment variable as above
|
|
43
|
-
- The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) plugin requires the following environment variables:
|
|
34
|
+
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:
|
|
44
35
|
|
|
45
36
|
| Variable | Description |
|
|
46
37
|
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
47
38
|
| `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. |
|
|
39
|
+
| `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. |
|
|
48
40
|
|
|
49
41
|
See each plugin's documentation for the environment variables required.
|
|
50
42
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
43
|
+
The authentication token/credentials have to be made available in the CI service via environment variables.
|
|
44
|
+
|
|
45
|
+
See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
|
|
46
|
+
|
|
47
|
+
**Note**: The environment variables `GH_TOKEN`, `GITHUB_TOKEN`, `GL_TOKEN` and `GITLAB_TOKEN` can be used for both the Git authentication and the API authentication required by [@semantic-release/github](https://github.com/semantic-release/github) and [@semantic-release/gitlab](https://github.com/semantic-release/gitlab).
|
|
@@ -1,93 +1,64 @@
|
|
|
1
1
|
# Configuration
|
|
2
2
|
|
|
3
3
|
**semantic-release** configuration consists of:
|
|
4
|
-
- Git repository [
|
|
5
|
-
- Plugins [declaration](#plugins) and
|
|
6
|
-
- Run mode ([
|
|
4
|
+
- Git repository ([URL](#repositoryurl) and options [release branch](#branch) and [tag format](#tagformat))
|
|
5
|
+
- Plugins [declaration](#plugins) and options
|
|
6
|
+
- Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci))
|
|
7
7
|
|
|
8
|
-
All of these options can be configured
|
|
9
|
-
- In a config file.
|
|
10
|
-
- Through the cli.
|
|
11
|
-
- By extending a [shareable configuration](shareable-configurations.md).
|
|
8
|
+
All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](shareable-configurations.md).
|
|
12
9
|
|
|
13
10
|
Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables).
|
|
14
11
|
|
|
15
|
-
##
|
|
12
|
+
## Configuration file
|
|
16
13
|
|
|
17
|
-
|
|
14
|
+
**semantic-release**’s [options](#options), mode and [plugins](plugins.md) can be set via either:
|
|
15
|
+
- A `.releaserc` file, written in YAML or JSON, with optional extensions: .`yaml`/`.yml`/`.json`/`.js`
|
|
16
|
+
- A `release.config.js` file that exports an object
|
|
17
|
+
- A `release` key in the project's `package.json` file
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Alternatively, some options can be set via CLI arguments.
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
- A `.releaserc` file, written in YAML or JSON, with optional extensions `.yaml`, `.yml`, `.json` or `.js`.
|
|
23
|
-
- A `release.config.js` file that exports an object.
|
|
24
|
-
- A `release` key in the project's `package.json` file.
|
|
21
|
+
The following three examples are the same.
|
|
25
22
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
```json
|
|
35
|
-
{
|
|
36
|
-
"release": {
|
|
37
|
-
"branch": "next"
|
|
38
|
-
}
|
|
39
|
-
}
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### Using CLI arguments
|
|
43
|
-
|
|
44
|
-
> **Note**: CLI arguments take precedence over options configured in the configuration file and shareable configuration.
|
|
45
|
-
|
|
46
|
-
Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
|
|
23
|
+
- Via `release` key in the project's `package.json` file:
|
|
24
|
+
```json
|
|
25
|
+
{
|
|
26
|
+
"release": {
|
|
27
|
+
"branch": "next"
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
47
31
|
|
|
48
|
-
|
|
32
|
+
- Via `.releaserc` file:
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"branch": "next"
|
|
36
|
+
}
|
|
37
|
+
```
|
|
49
38
|
|
|
39
|
+
- Via CLI argument:
|
|
50
40
|
```bash
|
|
51
41
|
$ semantic-release --branch next
|
|
52
42
|
```
|
|
53
43
|
|
|
54
|
-
|
|
44
|
+
**Note**: CLI arguments take precedence over options configured in the configuration file.
|
|
55
45
|
|
|
56
|
-
|
|
46
|
+
**Note**: Plugin options cannot be defined via CLI arguments and must be defined in the configuration file.
|
|
57
47
|
|
|
58
|
-
|
|
48
|
+
**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.
|
|
59
49
|
|
|
60
50
|
## Options
|
|
61
51
|
|
|
62
|
-
###
|
|
52
|
+
### extends
|
|
63
53
|
|
|
64
54
|
Type: `Array`, `String`<br>
|
|
65
55
|
CLI arguments: `-e`, `--extends`
|
|
66
56
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
Examples (`.releaserc` file content):
|
|
74
|
-
- `Array`:
|
|
75
|
-
```json
|
|
76
|
-
{
|
|
77
|
-
"extends": [
|
|
78
|
-
"./my_config_dir/my.config",
|
|
79
|
-
"@semantic-release/gitlab-config",
|
|
80
|
-
]
|
|
81
|
-
}
|
|
82
|
-
```
|
|
83
|
-
- `String`:
|
|
84
|
-
```json
|
|
85
|
-
{
|
|
86
|
-
"extends": "@semantic-release/gitlab-config"
|
|
87
|
-
}
|
|
88
|
-
```
|
|
89
|
-
|
|
90
|
-
### `branch`
|
|
57
|
+
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.
|
|
58
|
+
|
|
59
|
+
**Note**: Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration.
|
|
60
|
+
|
|
61
|
+
### branch
|
|
91
62
|
|
|
92
63
|
Type: `String`<br>
|
|
93
64
|
Default: `master`<br>
|
|
@@ -95,14 +66,7 @@ CLI arguments: `-b`, `--branch`
|
|
|
95
66
|
|
|
96
67
|
The branch on which releases should happen.
|
|
97
68
|
|
|
98
|
-
|
|
99
|
-
```json
|
|
100
|
-
{
|
|
101
|
-
"branch": "next"
|
|
102
|
-
}
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
### `repositoryUrl`
|
|
69
|
+
### repositoryUrl
|
|
106
70
|
|
|
107
71
|
Type: `String`<br>
|
|
108
72
|
Default: `repository` property in `package.json` or [git origin url](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes)<br>
|
|
@@ -112,14 +76,7 @@ The git repository URL.
|
|
|
112
76
|
|
|
113
77
|
Any valid git url format is supported (See [Git protocols](https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols)).
|
|
114
78
|
|
|
115
|
-
|
|
116
|
-
```json
|
|
117
|
-
{
|
|
118
|
-
"repositoryUrl": "https://github.com/username/project.git"
|
|
119
|
-
}
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
### `tagFormat`
|
|
79
|
+
### tagFormat
|
|
123
80
|
|
|
124
81
|
Type: `String`<br>
|
|
125
82
|
Default: `v${version}`<br>
|
|
@@ -127,41 +84,21 @@ CLI arguments: `-t`, `--tag-format`
|
|
|
127
84
|
|
|
128
85
|
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.
|
|
129
86
|
|
|
130
|
-
|
|
87
|
+
**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).
|
|
131
88
|
|
|
132
|
-
|
|
133
|
-
```json
|
|
134
|
-
{
|
|
135
|
-
"tagFormat": "version-${version}"
|
|
136
|
-
}
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
### `plugins`
|
|
89
|
+
### plugins
|
|
140
90
|
|
|
141
91
|
Type: `Array`<br>
|
|
142
92
|
Default: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`<br>
|
|
143
93
|
CLI arguments: `-p`, `--plugins`
|
|
144
94
|
|
|
145
|
-
Define the list of plugins to use. Plugins will run in series,
|
|
95
|
+
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.
|
|
146
96
|
|
|
147
|
-
|
|
97
|
+
Plugins configuration can defined by wrapping the name and an options object in an array.
|
|
148
98
|
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
"plugins": [
|
|
153
|
-
"@semantic-release/commit-analyzer",
|
|
154
|
-
"@semantic-release/release-notes-generator",
|
|
155
|
-
"@semantic-release-docker",
|
|
156
|
-
["@semantic-release/exec", {
|
|
157
|
-
"verifyConditionsCmd": "./verify.sh"
|
|
158
|
-
}],
|
|
159
|
-
"@semantic-release/git",
|
|
160
|
-
"@semantic-release/gitlab",
|
|
161
|
-
]
|
|
162
|
-
}
|
|
163
|
-
```
|
|
164
|
-
### `dryRun`
|
|
99
|
+
See [Plugins configuration](plugins.md#plugins) for more details.
|
|
100
|
+
|
|
101
|
+
### dryRun
|
|
165
102
|
|
|
166
103
|
Type: `Boolean`<br>
|
|
167
104
|
Default: `false` if running in a CI environment, `true` otherwise<br>
|
|
@@ -169,14 +106,7 @@ CLI arguments: `-d`, `--dry-run`
|
|
|
169
106
|
|
|
170
107
|
Dry-run mode, skip publishing, print next version and release notes.
|
|
171
108
|
|
|
172
|
-
|
|
173
|
-
```json
|
|
174
|
-
{
|
|
175
|
-
"dryRun": "true"
|
|
176
|
-
}
|
|
177
|
-
```
|
|
178
|
-
|
|
179
|
-
### `ci`
|
|
109
|
+
### ci
|
|
180
110
|
|
|
181
111
|
Type: `Boolean`<br>
|
|
182
112
|
Default: `true`<br>
|
|
@@ -184,16 +114,9 @@ CLI arguments: `--ci` / `--no-ci`
|
|
|
184
114
|
|
|
185
115
|
Set to `false` to skip Continuous Integration environment verifications. This allows for making releases from a local machine.
|
|
186
116
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
Example (`.releaserc` file content):
|
|
190
|
-
```json
|
|
191
|
-
{
|
|
192
|
-
"ci": "false"
|
|
193
|
-
}
|
|
194
|
-
```
|
|
117
|
+
**Note**: The CLI arguments `--no-ci` is equivalent to `--ci false`.
|
|
195
118
|
|
|
196
|
-
###
|
|
119
|
+
### debug
|
|
197
120
|
|
|
198
121
|
Type: `Boolean`<br>
|
|
199
122
|
Default: `false`<br>
|
|
@@ -201,12 +124,7 @@ CLI argument: `--debug`
|
|
|
201
124
|
|
|
202
125
|
Output debugging information. This can also be enabled by setting the `DEBUG` environment variable to `semantic-release:*`.
|
|
203
126
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
Example:
|
|
207
|
-
```bash
|
|
208
|
-
$ semantic-release --debug
|
|
209
|
-
```
|
|
127
|
+
**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:*')`.
|
|
210
128
|
|
|
211
129
|
## Git environment variables
|
|
212
130
|
|
|
@@ -217,10 +135,9 @@ $ semantic-release --debug
|
|
|
217
135
|
| `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. |
|
|
218
136
|
| `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. |
|
|
219
137
|
|
|
220
|
-
## Existing version tags
|
|
221
|
-
|
|
222
|
-
**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release.
|
|
138
|
+
## Existing version tags
|
|
223
139
|
|
|
140
|
+
**semantic-release** uses [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) to determine the commits added since the last release.
|
|
224
141
|
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`).
|
|
225
142
|
|
|
226
143
|
If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
In order to use **semantic-release** you must follow these steps:
|
|
4
|
+
1. [Install](./installation.md#installation) **semantic-release** in your project
|
|
5
|
+
2. Configure your Continuous Integration service to [run **semantic-release**](./ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
|
|
6
|
+
3. Configure your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
|
|
7
|
+
4. Configure **semantic-release** [options and plugins](./configuration.md#configuration)
|
|
8
|
+
|
|
9
|
+
Alternatively those steps can be easily done with the [**semantic-release** interactive CLI](https://github.com/semantic-release/cli):
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g semantic-release-cli
|
|
13
|
+
|
|
14
|
+
cd your-module
|
|
15
|
+
semantic-release-cli setup
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
See the [semantic-release-cli](https://github.com/semantic-release/cli#what-it-does) documentation for more details.
|
|
21
|
+
|
|
22
|
+
**Note**: only a limited number of options, CI services and plugins are currently supported by `semantic-release-cli`.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Installation
|
|
2
|
+
|
|
3
|
+
## Local installation
|
|
4
|
+
|
|
5
|
+
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):
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
$ npm install --save-dev semantic-release
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Then in the CI environment:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
$ npx semantic-release
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
**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.
|
|
18
|
+
|
|
19
|
+
## Global installation
|
|
20
|
+
|
|
21
|
+
For other type of projects we recommend installing **semantic-release** directly in the CI environment, also with [npx](https://www.npmjs.com/package/npx):
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
$ npx semantic-release
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
**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`). 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.
|
|
28
|
+
|
|
29
|
+
**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.
|
|
@@ -1,15 +1,13 @@
|
|
|
1
1
|
# Plugins
|
|
2
2
|
|
|
3
|
-
|
|
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
4
|
|
|
5
|
-
|
|
5
|
+
A plugin is a npm module that can implement one or more of the following steps:
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
| Step hook | Required | Description |
|
|
7
|
+
| Step | Required | Description |
|
|
10
8
|
|--------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
11
9
|
| `verifyConditions` | No | Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc... |
|
|
12
|
-
| `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.
|
|
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. |
|
|
13
11
|
| `verifyRelease` | No | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published. |
|
|
14
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. |
|
|
15
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. |
|
|
@@ -17,22 +15,23 @@ A plugin is a npm module (for instance `@semantic-release/github` or `semantic-r
|
|
|
17
15
|
| `success` | No | Responsible for notifying of a new release. |
|
|
18
16
|
| `fail` | No | Responsible for notifying of a failed release. |
|
|
19
17
|
|
|
18
|
+
**Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used.
|
|
19
|
+
|
|
20
20
|
## Plugins installation
|
|
21
21
|
|
|
22
|
-
###
|
|
22
|
+
### Default plugins
|
|
23
23
|
|
|
24
|
-
These
|
|
24
|
+
These four plugins are already part of **semantic-release** and don't have to be installed separately:
|
|
25
25
|
```
|
|
26
|
-
"@semantic-release/commit-analyzer"
|
|
27
|
-
"@semantic-release/
|
|
28
|
-
"@semantic-release/
|
|
29
|
-
"@semantic-release/npm"
|
|
26
|
+
"@semantic-release/commit-analyzer"
|
|
27
|
+
"@semantic-release/github"
|
|
28
|
+
"@semantic-release/npm"
|
|
30
29
|
"@semantic-release/release-notes-generator"
|
|
31
30
|
```
|
|
32
31
|
|
|
33
|
-
###
|
|
32
|
+
### Additional plugins
|
|
34
33
|
|
|
35
|
-
[Additional plugins](../
|
|
34
|
+
[Additional plugins](../extending/plugins-list.md) have to be installed via npm:
|
|
36
35
|
|
|
37
36
|
```bash
|
|
38
37
|
$ npm install @semantic-release/git @semantic-release/changelog -D
|
|
@@ -40,9 +39,18 @@ $ npm install @semantic-release/git @semantic-release/changelog -D
|
|
|
40
39
|
|
|
41
40
|
## Plugins declaration and execution order
|
|
42
41
|
|
|
43
|
-
Each plugin
|
|
42
|
+
Each plugin must be configured with the [`plugins` options](./configuration.md#plugins) by specifying the list of plugins by npm module name.
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"plugins": ["@semantic-release/commit-analyzer", "@semantic-release/release-notes-generator", "@semantic-release/npm"]
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
**Note:** If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it.
|
|
51
|
+
|
|
52
|
+
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.
|
|
44
53
|
|
|
45
|
-
For example:
|
|
46
54
|
```json
|
|
47
55
|
{
|
|
48
56
|
"plugins": [
|
|
@@ -54,20 +62,18 @@ For example:
|
|
|
54
62
|
}
|
|
55
63
|
```
|
|
56
64
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
Hence, with this configuration above, **semantic-release** will:
|
|
65
|
+
With this configuration **semantic-release** will:
|
|
60
66
|
- execute the `verifyConditions` implementation of `@semantic-release/npm` then `@semantic-release/git`
|
|
61
67
|
- execute the `analyzeCommits` implementation of `@semantic-release/commit-analyzer`
|
|
62
68
|
- execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git`
|
|
63
69
|
- execute the `generateNotes` implementation of `@semantic-release/release-notes-generator`
|
|
64
70
|
- execute the `publish` implementation of `@semantic-release/npm`
|
|
65
71
|
|
|
66
|
-
##
|
|
72
|
+
## Plugin options configuration
|
|
67
73
|
|
|
68
|
-
A plugin configuration
|
|
74
|
+
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.
|
|
69
75
|
|
|
70
|
-
Global plugin
|
|
76
|
+
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.
|
|
71
77
|
|
|
72
78
|
```json
|
|
73
79
|
{
|
|
@@ -0,0 +1,7 @@
|
|
|
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).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "semantic-release",
|
|
3
3
|
"description": "Automated semver compliant package publishing",
|
|
4
|
-
"version": "15.13.
|
|
4
|
+
"version": "15.13.24",
|
|
5
5
|
"author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
|
|
6
6
|
"ava": {
|
|
7
7
|
"files": [
|
|
@@ -17,11 +17,6 @@
|
|
|
17
17
|
"bugs": {
|
|
18
18
|
"url": "https://github.com/semantic-release/semantic-release/issues"
|
|
19
19
|
},
|
|
20
|
-
"config": {
|
|
21
|
-
"commitizen": {
|
|
22
|
-
"path": "cz-conventional-changelog"
|
|
23
|
-
}
|
|
24
|
-
},
|
|
25
20
|
"contributors": [
|
|
26
21
|
"Gregor Martynus (https://twitter.com/gr2m)",
|
|
27
22
|
"Pierre Vanduynslager (https://twitter.com/@pvdlg_)"
|
|
@@ -42,7 +37,7 @@
|
|
|
42
37
|
"get-stream": "^5.0.0",
|
|
43
38
|
"git-log-parser": "^1.2.0",
|
|
44
39
|
"hook-std": "^2.0.0",
|
|
45
|
-
"hosted-git-info": "^
|
|
40
|
+
"hosted-git-info": "^3.0.0",
|
|
46
41
|
"lodash": "^4.17.15",
|
|
47
42
|
"marked": "^0.7.0",
|
|
48
43
|
"marked-terminal": "^3.2.0",
|
|
@@ -52,14 +47,12 @@
|
|
|
52
47
|
"resolve-from": "^5.0.0",
|
|
53
48
|
"semver": "^6.0.0",
|
|
54
49
|
"signale": "^1.2.1",
|
|
55
|
-
"yargs": "^
|
|
50
|
+
"yargs": "^14.0.0"
|
|
56
51
|
},
|
|
57
52
|
"devDependencies": {
|
|
58
53
|
"ava": "^2.0.0",
|
|
59
54
|
"clear-module": "^4.0.0",
|
|
60
55
|
"codecov": "^3.0.0",
|
|
61
|
-
"commitizen": "^4.0.0",
|
|
62
|
-
"cz-conventional-changelog": "^2.0.0",
|
|
63
56
|
"delay": "^4.0.0",
|
|
64
57
|
"dockerode": "^2.5.2",
|
|
65
58
|
"file-url": "^3.0.0",
|
|
@@ -125,7 +118,6 @@
|
|
|
125
118
|
"url": "git+https://github.com/semantic-release/semantic-release.git"
|
|
126
119
|
},
|
|
127
120
|
"scripts": {
|
|
128
|
-
"cm": "git-cz",
|
|
129
121
|
"codecov": "codecov -f coverage/coverage-final.json",
|
|
130
122
|
"lint": "xo",
|
|
131
123
|
"pretest": "npm run lint",
|
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
# Getting started
|
|
2
|
-
|
|
3
|
-
## Manual setup
|
|
4
|
-
|
|
5
|
-
You can use **semantic-release** with the following manual setup steps:
|
|
6
|
-
|
|
7
|
-
1. [Install **semantic-release**](installation.md) either locally for your project or globally
|
|
8
|
-
1. Configure:
|
|
9
|
-
1. Your Continuous Integration service to [run **semantic-release**](ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded)
|
|
10
|
-
1. Your Git repository and package manager repository [authentication](ci-configuration.md#authentication) in your Continuous Integration service
|
|
11
|
-
1. **semantic-release**'s [options and plugins](configuration.md)
|
|
12
|
-
|
|
13
|
-
## Guided setup through `semantic-release-cli`
|
|
14
|
-
Alternatively you can be guided through those setup steps thanks to the [interactive CLI `semantic-release-cli`](https://github.com/semantic-release/cli).
|
|
15
|
-
|
|
16
|
-
First install `semantic-release-cli`:
|
|
17
|
-
```bash
|
|
18
|
-
$ npm install -g semantic-release-cli
|
|
19
|
-
```
|
|
20
|
-
|
|
21
|
-
Then go to your project's directory and run the command:
|
|
22
|
-
```bash
|
|
23
|
-
$ cd your-module
|
|
24
|
-
$ semantic-release-cli setup
|
|
25
|
-
```
|
|
26
|
-
The output looks something like this:
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
Available options and other information can be found on [`semantic-release-cli`'s doc](https://github.com/semantic-release/cli#semantic-release-cli).
|
|
31
|
-
|
|
32
|
-
> **Note**: only a limited number of options, CI services and plugins are currently supported by `semantic-release-cli`.
|
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
# Installation
|
|
2
|
-
|
|
3
|
-
## Local installation
|
|
4
|
-
|
|
5
|
-
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):
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
$ npm install --save-dev semantic-release
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
Then in the CI environment:
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
$ npx semantic-release
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
> **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.
|
|
18
|
-
|
|
19
|
-
## Global installation
|
|
20
|
-
|
|
21
|
-
> **Note:** For a global installation is no longer recommended. Please use local installation and `npx` instead.
|
|
22
|
-
|
|
@@ -1,7 +0,0 @@
|
|
|
1
|
-
# Shareable configurations
|
|
2
|
-
|
|
3
|
-
A shareable configuration is an npm package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects.
|
|
4
|
-
|
|
5
|
-
Shareable configurations to be use can be declared with the [`extends` option](configuration.md#extends).
|
|
6
|
-
|
|
7
|
-
See [shareable configurations list](../02-extending/shareable-configurations-list.md) for examples.
|