semantic-release 18.0.0-beta.6 → 18.0.1

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 (26) hide show
  1. package/README.md +25 -22
  2. package/docs/README.md +1 -1
  3. package/docs/developer-guide/plugin.md +18 -4
  4. package/docs/extending/plugins-list.md +18 -1
  5. package/docs/recipes/ci-configurations/README.md +6 -0
  6. package/docs/recipes/{circleci-workflows.md → ci-configurations/circleci-workflows.md} +9 -16
  7. package/docs/recipes/{github-actions.md → ci-configurations/github-actions.md} +5 -5
  8. package/docs/recipes/{gitlab-ci.md → ci-configurations/gitlab-ci.md} +5 -5
  9. package/docs/recipes/{jenkins-ci.md → ci-configurations/jenkins-ci.md} +10 -10
  10. package/docs/recipes/{travis.md → ci-configurations/travis.md} +6 -6
  11. package/docs/recipes/git-hosted-services/README.md +2 -0
  12. package/docs/recipes/{git-auth-ssh-keys.md → git-hosted-services/git-auth-ssh-keys.md} +1 -1
  13. package/docs/recipes/release-workflow/README.md +4 -0
  14. package/docs/recipes/{distribution-channels.md → release-workflow/distribution-channels.md} +2 -2
  15. package/docs/recipes/{maintenance-releases.md → release-workflow/maintenance-releases.md} +3 -3
  16. package/docs/recipes/{pre-releases.md → release-workflow/pre-releases.md} +2 -2
  17. package/docs/support/FAQ.md +9 -19
  18. package/docs/support/git-version.md +4 -0
  19. package/docs/support/node-support-policy.md +13 -5
  20. package/docs/support/node-version.md +12 -11
  21. package/docs/support/troubleshooting.md +1 -1
  22. package/docs/usage/ci-configuration.md +3 -3
  23. package/docs/usage/installation.md +4 -2
  24. package/docs/usage/workflow-configuration.md +4 -4
  25. package/package.json +12 -12
  26. package/docs/recipes/README.md +0 -18
package/README.md CHANGED
@@ -23,9 +23,9 @@
23
23
  </a>
24
24
  </p>
25
25
 
26
- **semantic-release** automates the whole package release workflow including: determining the next version number, generating the release notes and publishing the package.
26
+ **semantic-release** automates the whole package release workflow including: determining the next version number, generating the release notes, and publishing the package.
27
27
 
28
- This removes the immediate connection between human emotions and version numbers, strictly following the [Semantic Versioning](http://semver.org) specification.
28
+ This removes the immediate connection between human emotions and version numbers, strictly following the [Semantic Versioning](http://semver.org) specification and communicating the **impact** of changes to consumers.
29
29
 
30
30
  > Trust us, this will change your workflow for the better. – [egghead.io](https://egghead.io/lessons/javascript-how-to-write-a-javascript-library-automating-releases-with-semantic-release)
31
31
 
@@ -37,18 +37,20 @@ This removes the immediate connection between human emotions and version numbers
37
37
  - Notify maintainers and users of new releases
38
38
  - Use formalized commit message convention to document changes in the codebase
39
39
  - Publish on different distribution channels (such as [npm dist-tags](https://docs.npmjs.com/cli/dist-tag)) based on git merges
40
- - Integrate with your [continuous integration workflow](docs/recipes/README.md#ci-configurations)
40
+ - Integrate with your [continuous integration workflow](docs/recipes/release-workflow/README.md#ci-configurations)
41
41
  - Avoid potential errors associated with manual releases
42
- - Support any [package managers and languages](docs/recipes/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
42
+ - Support any [package managers and languages](docs/recipes/release-workflow/README.md#package-managers-and-languages) via [plugins](docs/usage/plugins.md)
43
43
  - Simple and reusable configuration via [shareable configurations](docs/usage/shareable-configurations.md)
44
44
 
45
45
  ## How does it work?
46
46
 
47
47
  ### Commit message format
48
48
 
49
- **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.
49
+ **semantic-release** uses the commit messages to determine the consumer impact of changes in the codebase.
50
+ 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.
50
51
 
51
- By default **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format). 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.
52
+ By default, **semantic-release** uses [Angular Commit Message Conventions](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-format).
53
+ 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.
52
54
 
53
55
  Tools such as [commitizen](https://github.com/commitizen/cz-cli) or [commitlint](https://github.com/conventional-changelog/commitlint) can be used to help contributors and enforce valid commit messages.
54
56
 
@@ -56,23 +58,25 @@ The table below shows which commit message gets you which release type when `sem
56
58
 
57
59
  | Commit message | Release type |
58
60
  | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
59
- | `fix(pencil): stop graphite breaking when too much pressure applied` | Patch Release |
61
+ | `fix(pencil): stop graphite breaking when too much pressure applied` | ~~Patch~~ Fix Release |
60
62
  | `feat(pencil): add 'graphiteWidth' option` | ~~Minor~~ Feature Release |
61
63
  | `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release |
62
64
 
63
65
  ### Automation with CI
64
66
 
65
- **semantic-release** is meant to be executed on the CI environment after every successful build on the release branch. This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org).
67
+ **semantic-release** is meant to be executed on the CI environment after every successful build on the release branch.
68
+ This way no human is directly involved in the release process and the releases are guaranteed to be [unromantic and unsentimental](http://sentimentalversioning.org).
66
69
 
67
70
  ### Triggering a release
68
71
 
69
- For each new commits added to one of the release branches (for example `master`, `next`, `beta`), 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
+ For each new commit added to one of the release branches (for example: `master`, `next`, `beta`), 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.
70
73
 
71
- **semantic-release** offers various ways to control the timing, the content and the audience of published releases. See example workflows in the following recipes:
74
+ **semantic-release** offers various ways to control the timing, the content and the audience of published releases.
75
+ See example workflows in the following recipes:
72
76
 
73
- - [Using distribution channels](docs/recipes/distribution-channels.md#publishing-on-distribution-channels)
74
- - [Maintenance releases](docs/recipes/maintenance-releases.md#publishing-maintenance-releases)
75
- - [Pre-releases](docs/recipes/pre-releases.md#publishing-pre-releases)
77
+ - [Using distribution channels](docs/recipes/release-workflow/distribution-channels.md#publishing-on-distribution-channels)
78
+ - [Maintenance releases](docs/recipes/release-workflow/maintenance-releases.md#publishing-maintenance-releases)
79
+ - [Pre-releases](docs/recipes/release-workflow/pre-releases.md#publishing-pre-releases)
76
80
 
77
81
  ### Release steps
78
82
 
@@ -96,8 +100,8 @@ In order to use **semantic-release** you need:
96
100
 
97
101
  - To host your code in a [Git repository](https://git-scm.com)
98
102
  - Use a Continuous Integration service that allows you to [securely set up credentials](docs/usage/ci-configuration.md#authentication)
99
- - Git CLI version [2.7.1 or higher](docs/support/FAQ.md#why-does-semantic-release-require-git-version--271) installed in your Continuous Integration environment
100
- - [Node.js](https://nodejs.org) version [14.17 or higher](docs/support/FAQ.md#why-does-semantic-release-require-node-version--1417) installed in your Continuous Integration environment
103
+ - A Git CLI version that meets [our version requirement](docs/support/git-version.md) installed in your Continuous Integration environment
104
+ - A [Node.js](https://nodejs.org) version that meets [our version requirement](docs/support/node-version.md) installed in your Continuous Integration environment
101
105
 
102
106
  ## Documentation
103
107
 
@@ -113,10 +117,9 @@ In order to use **semantic-release** you need:
113
117
  - [Plugins](docs/extending/plugins-list.md)
114
118
  - [Shareable configuration](docs/extending/shareable-configurations-list.md)
115
119
  - Recipes
116
- - [CI configurations](docs/recipes/README.md)
117
- - [Git hosted services](docs/recipes/README.md)
118
- - [Release workflow](docs/recipes/README.md)
119
- - [Package managers and languages](docs/recipes/README.md)
120
+ - [CI configurations](docs/recipes/ci-configurations/README.md)
121
+ - [Git hosted services](docs/recipes/git-hosted-services/README.md)
122
+ - [Release workflow](docs/recipes/release-workflow/README.md)
120
123
  - Developer guide
121
124
  - [JavaScript API](docs/developer-guide/js-api.md)
122
125
  - [Plugins development](docs/developer-guide/plugin.md)
@@ -130,18 +133,18 @@ In order to use **semantic-release** you need:
130
133
 
131
134
  ## Get help
132
135
 
133
- - [Stack Overflow](https://stackoverflow.com/questions/tagged/semantic-release)
134
136
  - [GitHub Discussions](https://github.com/semantic-release/semantic-release/discussions)
137
+ - [Stack Overflow](https://stackoverflow.com/questions/tagged/semantic-release)
135
138
  - [Twitter](https://twitter.com/SemanticRelease)
136
139
 
137
140
  ## Badge
138
141
 
139
142
  Let people know that your package is published using **semantic-release** by including this badge in your readme.
140
143
 
141
- [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
144
+ [![semantic-release](https://img.shields.io/badge/semantic-release-e10079.svg?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
142
145
 
143
146
  ```md
144
- [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
147
+ [![semantic-release](https://img.shields.io/badge/semantic-release-e10079.svg?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
145
148
  ```
146
149
 
147
150
  ## Team
package/docs/README.md CHANGED
@@ -2,6 +2,6 @@
2
2
 
3
3
  - [Usage](usage/README.md) - **semantic-release** installation and configuration
4
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
5
+ - [Recipes](recipes/release-workflow/README.md) - Community written recipes for common **semantic-release** use-cases
6
6
  - [Developer Guide](developer-guide/README.md) - The essentials of writing a **semantic-release** plugin or shareable configurations
7
7
  - [Support](support/README.md) - FAQ and troubleshooting
package/docs/developer-guide/plugin.md CHANGED
@@ -34,7 +34,7 @@ We recommend you setup a linting system to ensure good javascript practices are
34
34
  In your `index.js` file, you can start by writing the following code
35
35
 
36
36
  ```javascript
37
- const verifyConditions = require('./src/verify');
37
+ const verify = require('./src/verify');
38
38
 
39
39
  let verified;
40
40
 
@@ -43,12 +43,12 @@ let verified;
43
43
  * @param {*} pluginConfig The semantic-release plugin config
44
44
  * @param {*} context The context provided by semantic-release
45
45
  */
46
- async function verify(pluginConfig, context) {
47
- await verifyConditions(pluginConfig, context);
46
+ async function verifyConditions(pluginConfig, context) {
47
+ await verify(pluginConfig, context);
48
48
  verified = true;
49
49
  }
50
50
 
51
- module.exports = { verify };
51
+ module.exports = { verifyConditions };
52
52
  ```
53
53
 
54
54
  Then, in your `src` folder, create a file called `verify.js` and add the following
@@ -237,6 +237,20 @@ if (env.GITHUB_TOKEN) {
237
237
  //...
238
238
  }
239
239
  ```
240
+ ## Logger
241
+ Use `context.logger` to provide debug logging in the plugin.
242
+
243
+ ```js
244
+ const { logger } = context;
245
+
246
+ logger.log('Some message from plugin.').
247
+ ```
248
+
249
+ The above usage yields the following where `PLUGIN_PACKAGE_NAME` is automatically inferred.
250
+
251
+ ```
252
+ [3:24:04 PM] [semantic-release] [PLUGIN_PACKAGE_NAME] › ℹ Some message from plugin.
253
+ ```
240
254
 
241
255
  ## Execution order
242
256
 
package/docs/extending/plugins-list.md CHANGED
@@ -54,7 +54,8 @@
54
54
  - `publish`: Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag
55
55
  - [@semantic-release-plus/docker](https://github.com/semantic-release-plus/semantic-release-plus/tree/master/packages/plugins/docker)
56
56
  - `verifyConditions`: Verify that all needed configuration is present and login to the configured docker registry.
57
- - `publish`: Tag the image specified by `name` with the new version, push it to the configured docker registry and update the `latest`, `major`, `minor` tags based on the configuration settings.
57
+ - `publish`: Tag the image specified by `name` with the new version and channel and push it to the configured docker registry.
58
+ - `addChannel`: Updates a release published on one channel with the destinations channel tag and pushes to the registry ie: next to latest.
58
59
  - [semantic-release-gcr](https://github.com/carlos-cubas/semantic-release-gcr)
59
60
  - `verifyConditions`: Verify that all needed configuration is present and login to the Docker registry
60
61
  - `publish`: Tag the image specified by `name` with the new version, push it to Docker Hub and update the latest tag
@@ -140,3 +141,19 @@
140
141
  - `verifyConditions`: Validate configuration and verify ```HEROKU_API_KEY```
141
142
  - `prepare`: Update the package.json version and create release tarball
142
143
  - `publish`: Publish version to heroku
144
+ - [semantic-release-mattermost](https://github.com/ttrobisch/semantic-release-mattermost)
145
+ - `verifyConditions`: Verify that the webhook is setup and release-notes-generator is present.
146
+ - `success`: Send a message about the new release and its notes to a [mattermost](https://mattermost.com/) webhook.
147
+ - [semantic-release-github-milestones](https://github.com/nitzano/semantic-release-github-milestones)
148
+ - `verifyConditions`: Verify github tokens are present and valid.
149
+ - `verifyRelease`: Display information regarding the matching github milestone.
150
+ - [semantic-release-telegram-bot](https://github.com/skoropadas/semantic-release-telegram-bot)
151
+ - `verifyConditions`: Validate configuration and verify `TELEGRAM_BOT_TOKEN` and package name
152
+ - `success`: Publish a success message to certain telegram chats
153
+ - `fail`: Publish a fail message to certain telegram chats
154
+ - [semantic-release-npm-deprecate](https://github.com/jpoehnelt/semantic-release-npm-deprecate)
155
+ - `publish`: Automatically mark old versions as deprecated.
156
+ - [@eshepelyuk/semantic-release-helm-oci](https://github.com/eshepelyuk/semantic-release-helm-oci)
157
+ - `verifyConditions`: Verify plugin configuration and login to Helm registry
158
+ - `prepare`: Package Helm chart to local folder
159
+ - `publish`: Publish Helm chart to OCI registry
package/docs/recipes/ci-configurations/README.md ADDED
@@ -0,0 +1,6 @@
1
+ # CI configurations
2
+ - [CircleCI 2.0 workflows](circleci-workflows.md)
3
+ - [Travis CI](travis.md)
4
+ - [GitLab CI](gitlab-ci.md)
5
+ - [GitHub Actions](github-actions.md)
6
+ - [Jenkins CI](jenkins-ci.md)
package/docs/recipes/{circleci-workflows.md → ci-configurations/circleci-workflows.md} RENAMED
@@ -2,19 +2,22 @@
2
2
 
3
3
  ## Environment variables
4
4
 
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)..
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](../usage/getting-started.md#getting-started).
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
 
11
11
  ### `.circleci/config.yml` configuration for multiple Node jobs
12
12
 
13
- This example is a minimal configuration for **semantic-release** with tests running against Node 16 and 14. See [CircleCI documentation](https://circleci.com/docs/2.0) for additional configuration options.
13
+ This example is a minimal configuration for **semantic-release** with tests running against Node 16 and 14.
14
+ See [CircleCI documentation](https://circleci.com/docs/2.0) for additional configuration options.
14
15
 
15
16
  In this example, the [`circleci/node`](https://circleci.com/developer/orbs/orb/circleci/node) orb is imported (Which makes some node operations easier), then a `release` job is defined which will run `semantic-release`.
16
17
 
17
- To run our `release` job, we have created a workflow named `test_and_release` which will run two jobs, `node/test`, which comes from the node orb and will test our application, and our release job. Here, we are actually making use of [matrix jobs](https://circleci.com/blog/circleci-matrix-jobs/) so that our single `node/test` job will actually be executed twice, once for Node version 16, and once for version 14. Finally, we call our release job with a `requires` parameter so that `release` will only run after `node/test` has successfully tested against v14 and v16.
18
+ To run our `release` job, we have created a workflow named `test_and_release` which will run two jobs, `node/test`, which comes from the node orb and will test our application, and our release job.
19
+ Here, we are actually making use of [matrix jobs](https://circleci.com/blog/circleci-matrix-jobs/) so that our single `node/test` job will actually be executed twice, once for Node version 16, and once for version 14.
20
+ Finally, we call our release job with a `requires` parameter so that `release` will run against the latest LTS version of node, only after `node/test` has successfully tested against v14 and v16.
18
21
 
19
22
  ```yaml
20
23
  version: 2.1
@@ -25,6 +28,8 @@ jobs:
25
28
  executor: node/default
26
29
  steps:
27
30
  - checkout
31
+ - node/install
32
+ lts: true
28
33
  - node/install-packages # Install and automatically cache packages
29
34
  # Run optional required steps before releasing
30
35
  # - run: npm run build-script
@@ -44,15 +49,3 @@ workflows:
44
49
  requires:
45
50
  - node/test
46
51
  ```
47
-
48
- ### `package.json` configuration for multiple Node jobs
49
-
50
- A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
51
-
52
- ```json
53
- {
54
- "devDependencies": {
55
- "semantic-release": "^18.0.0"
56
- }
57
- }
58
- ```
package/docs/recipes/{github-actions.md → ci-configurations/github-actions.md} RENAMED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Environment variables
4
4
 
5
- The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://help.github.com/en/articles/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables).
5
+ The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
6
6
 
7
7
  In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and-viewing-authentication-tokens) is required to publish a package to the npm registry. GitHub Actions [automatically populate](https://help.github.com/en/articles/virtual-environments-for-github-actions#github_token-secret) a [`GITHUB_TOKEN`](https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line) environment variable which can be used in Workflows.
8
8
 
@@ -10,11 +10,11 @@ In this example a publish type [`NPM_TOKEN`](https://docs.npmjs.com/creating-and
10
10
 
11
11
  [GitHub Actions](https://github.com/features/actions) support [Workflows](https://help.github.com/en/articles/configuring-workflows), allowing to run tests on multiple Node versions and publish a release only when all test pass.
12
12
 
13
- **Note**: The publish pipeline must run on [Node version >= 14.17](../support/FAQ.md#why-does-semantic-release-require-node-version--1417).
13
+ **Note**: The publish pipeline must run on a [Node version that meets our version requirement](../../support/node-version.md).
14
14
 
15
15
  ### `.github/workflows/release.yml` configuration for Node projects
16
16
 
17
- The following is a minimal configuration for [`semantic-release`](https://github.com/semantic-release/semantic-release) with a build running on Node 14.17 when a new commit is pushed to a `master` branch.
17
+ The following is a minimal configuration for [`semantic-release`](https://github.com/semantic-release/semantic-release) with a build running on the latest LTS version of Node when a new commit is pushed to a `master` branch.
18
18
  See [Configuring a Workflow](https://help.github.com/en/articles/configuring-a-workflow) for additional configuration options.
19
19
 
20
20
  ```yaml
@@ -33,9 +33,9 @@ jobs:
33
33
  with:
34
34
  fetch-depth: 0
35
35
  - name: Setup Node.js
36
- uses: actions/setup-node@v1
36
+ uses: actions/setup-node@v2
37
37
  with:
38
- node-version: '14.17'
38
+ node-version: 'lts/*'
39
39
  - name: Install dependencies
40
40
  run: npm ci
41
41
  - name: Release
package/docs/recipes/{gitlab-ci.md → ci-configurations/gitlab-ci.md} RENAMED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Environment variables
4
4
 
5
- The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
5
+ The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Protected variables](https://docs.gitlab.com/ce/ci/variables/README.html#protected-environment-variables).
6
6
 
7
7
  **Note**: Make sure to configure your release branch as [protected](https://docs.gitlab.com/ce/user/project/protected_branches.html) in order for the CI/CD build to access the protected variables.
8
8
 
@@ -10,13 +10,13 @@ The [Authentication](../usage/ci-configuration.md#authentication) environment va
10
10
 
11
11
  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.
12
12
 
13
- **Note**: The publish pipeline must run a [Node >= 14.17 version](../support/FAQ.md#why-does-semantic-release-require-node-version--1417).
13
+ **Note**: The publish pipeline must run a [Node version that meets our version requirement](../../support/node-version.md).
14
14
 
15
15
  ### `.gitlab-ci.yml` configuration for Node projects
16
16
 
17
17
  This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
18
18
 
19
- **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.
19
+ **Note**: The`semantic-release` execution command varies depending on whether you are using a [local](../../usage/installation.md#local-installation) or [global](../../usage/installation.md#global-installation) **semantic-release** installation.
20
20
 
21
21
  ```yaml
22
22
  # The release pipeline will run only if all jobs in the test pipeline are successful
@@ -50,7 +50,7 @@ publish:
50
50
 
51
51
  This example is a minimal configuration for **semantic-release** with a build running Node 10 and 12. See [GitLab CI - Configuration of your jobs with .gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/README.html) for additional configuration options.
52
52
 
53
- **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.
53
+ **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.
54
54
 
55
55
 
56
56
  ```yaml
@@ -83,7 +83,7 @@ release:
83
83
 
84
84
  ### `package.json` configuration
85
85
 
86
- A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
86
+ A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
87
87
 
88
88
  ```json
89
89
  {
package/docs/recipes/{jenkins-ci.md → ci-configurations/jenkins-ci.md} RENAMED
@@ -2,19 +2,19 @@
2
2
 
3
3
  ## Environment variables
4
4
 
5
- The [Authentication](../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
5
+ The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured in [Jenkins Project Settings](https://www.jenkins.io/doc/pipeline/tour/environment/)..
6
6
 
7
- Alternatively, the default `NPM_TOKEN` and `GH_TOKEN` can be easily [setup with semantic-release-cli](../usage/getting-started.md#getting-started).
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 project configuration
10
10
 
11
11
  ### `Jenkinsfile (Declarative Pipeline)` configuration for a Node.js job
12
12
 
13
- **Note**: The publish pipeline must run a [Node >= 14.17 version](../support/FAQ.md#why-does-semantic-release-require-node-version--1417).
13
+ **Note**: The publish pipeline must run a Node version that [meets our requirement](../../support/node-version.md).
14
14
 
15
- This example is a minimal configuration for **semantic-release** with a build running Node 14.17. See [Jenkins documentation](https://www.jenkins.io/doc/) for additional configuration options.
16
-
17
- 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.
15
+ This example is a minimal configuration for **semantic-release** with a build running a version of Node labelled as "node LTS".
16
+ Since versions of Node are manually downloaded and labelled, we recommend keeping the version used for the release steps up-to-date with the latest LTS version.
17
+ See the [Jenkins documentation](https://www.jenkins.io/doc/) for additional configuration options.
18
18
 
19
19
  ```yaml
20
20
  // The release stage in the pipeline will run only if the test stage in the pipeline is successful
@@ -31,11 +31,11 @@ pipeline {
31
31
  npm install
32
32
  npm test
33
33
  '''
34
- }
34
+ }
35
35
  }
36
36
  stage('Release') {
37
37
  tools {
38
- nodejs "node 14.17"
38
+ nodejs "node LTS"
39
39
  }
40
40
  steps {
41
41
  sh '''
@@ -50,7 +50,7 @@ pipeline {
50
50
 
51
51
  ### `package.json` configuration for a Node job
52
52
 
53
- A `package.json` is required only for [local](../usage/installation.md#local-installation) **semantic-release** installation.
53
+ A `package.json` is required only for [local](../../usage/installation.md#local-installation) **semantic-release** installation.
54
54
 
55
55
  ```json
56
56
  {
@@ -58,4 +58,4 @@ A `package.json` is required only for [local](../usage/installation.md#local-ins
58
58
  "semantic-release": "^18.0.0"
59
59
  }
60
60
  }
61
- ```
61
+ ```
package/docs/recipes/{travis.md → ci-configurations/travis.md} RENAMED
@@ -2,9 +2,9 @@
2
2
 
3
3
  ## Environment variables
4
4
 
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).
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](../usage/getting-started.md#getting-started).
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 14 and 16. 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](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
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](../usage/installation.md#local-installation) **semantic-release** installation.
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](../usage/installation.md#local-ins
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](../support/FAQ.md#can-i-use-semantic-release-to-publish-non-javascript-packages) for more information on the **semantic-release** configuration.
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](../usage/ci-configuration.md#run-semantic-release-only-after-all-tests-succeeded).
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
 
package/docs/recipes/git-hosted-services/README.md ADDED
@@ -0,0 +1,2 @@
1
+ # Git hosted services
2
+ - [Git authentication with SSH keys](git-auth-ssh-keys.md)
package/docs/recipes/{git-auth-ssh-keys.md → git-hosted-services/git-auth-ssh-keys.md} RENAMED
@@ -1,6 +1,6 @@
1
1
  # Git authentication with SSH keys
2
2
 
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).
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
 
package/docs/recipes/release-workflow/README.md ADDED
@@ -0,0 +1,4 @@
1
+ # Release workflow
2
+ - [Publishing on distribution channels](distribution-channels.md)
3
+ - [Publishing maintenance releases](maintenance-releases.md)
4
+ - [Publishing pre-releases](pre-releases.md)
package/docs/recipes/{distribution-channels.md → release-workflow/distribution-channels.md} RENAMED
@@ -3,8 +3,8 @@
3
3
  This recipe will walk you through a simple example that uses distribution channels to make releases available only to a subset of users, in order to collect feedbacks before distributing the release to all users.
4
4
 
5
5
  This example uses the **semantic-release** default configuration:
6
- - [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
- - [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
6
+ - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
+ - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
8
8
 
9
9
  ## Initial release
10
10
 
package/docs/recipes/{maintenance-releases.md → release-workflow/maintenance-releases.md} RENAMED
@@ -3,8 +3,8 @@
3
3
  This recipe will walk you through a simple example that uses Git branches and distribution channels to publish fixes and features for old versions of a package.
4
4
 
5
5
  This example uses the **semantic-release** default configuration:
6
- - [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
- - [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
6
+ - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
+ - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
8
8
 
9
9
  ## Initial release
10
10
 
@@ -18,7 +18,7 @@ The Git history of the repository is:
18
18
 
19
19
  ## Releasing a breaking change
20
20
 
21
- We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
21
+ We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
22
22
 
23
23
  We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
24
24
 
package/docs/recipes/{pre-releases.md → release-workflow/pre-releases.md} RENAMED
@@ -3,8 +3,8 @@
3
3
  This recipe will walk you through a simple example that uses pre-releases to publish beta versions while working on a future major release and then make only one release on the default distribution.
4
4
 
5
5
  This example uses the **semantic-release** default configuration:
6
- - [branches](../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
- - [plugins](../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
6
+ - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
7
+ - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
8
8
 
9
9
  ## Initial release
10
10
 
package/docs/support/FAQ.md CHANGED
@@ -45,11 +45,11 @@ Yes, **semantic-release** is a Node CLI application, but it can be used to publi
45
45
  To publish a non-Node package (without a `package.json`) you would need to:
46
46
  - Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
47
47
  - Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or rc file](../usage/configuration.md#configuration)
48
- - Make sure your CI job executing the `semantic-release` command has access to [Node >= 14.17](#why-does-semantic-release-require-node-version--1417) to execute the `semantic-release` command
48
+ - Make sure your CI job executing the `semantic-release` command has access to a version of Node that [meets our version requirement](./node-version.md) to execute the `semantic-release` command
49
49
 
50
- See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
50
+ See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
51
51
 
52
- 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.
52
+ 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.
53
53
 
54
54
  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.
55
55
 
@@ -71,7 +71,7 @@ Here is a basic example to create [GitHub releases](https://help.github.com/arti
71
71
 
72
72
  **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.
73
73
 
74
- See the [package managers and languages recipes](../recipes/README.md#package-managers-and-languages) for more details on specific project types.
74
+ See the [package managers and languages recipes](../recipes/release-workflow/README.md#package-managers-and-languages) for more details on specific project types.
75
75
 
76
76
  ## Can I use semantic-release with any CI service?
77
77
 
@@ -79,7 +79,7 @@ Yes, **semantic-release** can be used with any CI service, as long as it provide
79
79
  - A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
80
80
  - 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)
81
81
 
82
- See the [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on specific CI environments.
82
+ See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
83
83
 
84
84
  ## Can I run semantic-release on my local machine rather than on a CI server?
85
85
 
@@ -95,7 +95,7 @@ However this is not the recommended approach, as running unit and integration te
95
95
 
96
96
  Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
97
97
 
98
- See the [GitLab CI recipes](../recipes/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
98
+ See the [GitLab CI recipes](../recipes/ci-configurations/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
99
99
 
100
100
  ## Can I use semantic-release with any Git hosted environment?
101
101
 
@@ -194,25 +194,15 @@ If you need more control over the timing of releases, see [Triggering a release]
194
194
 
195
195
  This is not supported by **semantic-release** as it's not considered a good practice, mostly because [Semantic Versioning](https://semver.org) rules applies differently to major version zero.
196
196
 
197
- If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/pre-releases.md#publishing-pre-releases).
197
+ If your project is under heavy development, with frequent breaking changes, and is not production ready yet we recommend [publishing pre-releases](../recipes/release-workflow/pre-releases.md#publishing-pre-releases).
198
198
 
199
199
  See [“Introduction to SemVer” - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2) for more details on [Semantic Versioning](https://semver.org) and the recommendation to start at version `1.0.0`.
200
200
 
201
201
  ## Can I trust semantic-release with my releases?
202
202
 
203
- **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).
203
+ **semantic-release** has a full unit and integration test suite that tests `npm` publishes against the [verdaccio](https://www.npmjs.com/package/verdaccio).
204
204
 
205
- 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).
206
-
207
- ## Why does semantic-release require Node version >= 14.17?
208
-
209
- **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 14.17 or higher**.
210
-
211
- See [Node version requirement](./node-version.md#node-version-requirement) for more details and solutions.
212
-
213
- ## Why does semantic-release require Git version >= 2.7.1?
214
-
215
- **semantic-release** uses Git CLI commands to read information about the repository such as branches, commit history and tags. Certain commands and options (such as [the `--merged` option of the `git tag` command](https://git-scm.com/docs/git-tag/2.7.0#git-tag---no-mergedltcommitgt) or bug fixes related to `git ls-files`) used by **semantic-release** are only available in Git version 2.7.1 and higher.
205
+ 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).
216
206
 
217
207
  ## What is npx?
218
208
 
package/docs/support/git-version.md ADDED
@@ -0,0 +1,4 @@
1
+ # Git version requirement
2
+
3
+ **semantic-release** uses Git CLI commands to read information about the repository such as branches, commit history and tags.
4
+ Certain commands and options (such as [the `--merged` option of the `git tag` command](https://git-scm.com/docs/git-tag/2.7.0#git-tag---no-mergedltcommitgt) or bug fixes related to `git ls-files`) used by **semantic-release** are only available in Git version 2.7.1 and higher.
package/docs/support/node-support-policy.md CHANGED
@@ -1,13 +1,21 @@
1
1
  # Node Support Policy
2
2
 
3
- We only support [Long-Term Support](https://github.com/nodejs/Release) versions of Node starting with [Node 14.17.0 (LTS)](https://nodejs.org/en/blog/release/v14.17.0).
3
+ We will always support at least the latest [Long-Term Support](https://github.com/nodejs/Release) version of Node, but provide no promise of support for older versions.
4
+ The supported range will always be defined in the `engines.node` property of the `package.json` of our packages.
4
5
 
5
6
  We specifically limit our support to LTS versions of Node, not because this package won't work on other versions, but because we have a limited amount of time, and supporting LTS offers the greatest return on that investment.
6
7
 
7
- It's possible this package will work correctly on newer versions of Node. It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.
8
+ It's possible this package will work correctly on newer versions of Node.
9
+ It may even be possible to use this package on older versions of Node, though that's more unlikely as we'll make every effort to take advantage of features available in the oldest LTS version we support.
8
10
 
9
- As each Node LTS version reaches its end-of-life we will remove that version from the node engines property of our package's package.json file. Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package. We will not accept any requests to support an end-of-life version of Node. Any merge requests or issues supporting an end-of-life version of Node will be closed.
11
+ As new Node LTS versions become available we may remove previous versions from the `engines.node` property of our package's `package.json` file.
12
+ Removing a Node version is considered a breaking change and will entail the publishing of a new major version of this package.
13
+ We will not accept any requests to support an end-of-life version of Node.
14
+ Any merge requests or issues supporting an end-of-life version of Node will be closed.
10
15
 
11
- We will accept code that allows this package to run on newer, non-LTS, versions of Node. Furthermore, we will attempt to ensure our own changes work on the latest version of Node. To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.
16
+ We will accept code that allows this package to run on newer, non-LTS, versions of Node.
17
+ Furthermore, we will attempt to ensure our own changes work on the latest version of Node.
18
+ To help in that commitment, our continuous integration setup runs against all LTS versions of Node in addition the most recent Node release; called current.
12
19
 
13
- JavaScript package managers should allow you to install this package with any version of Node, with, at most, a warning if your version of Node does not fall within the range specified by our node engines property. If you encounter issues installing this package, please report the issue to your package manager.
20
+ JavaScript package managers should allow you to install this package with any version of Node, with, at most, a warning if your version of Node does not fall within the range specified by our node engines property.
21
+ If you encounter issues installing this package, please report the issue to your package manager.
package/docs/support/node-version.md CHANGED
@@ -2,36 +2,37 @@
2
2
 
3
3
  **semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which requires **requires Node version 14.17 or higher**.
4
4
 
5
- **semantic-release** is meant to be used in a CI environment as a development support tool, not as a production dependency. Therefore, the only constraint is to run the `semantic-release` in a CI environment providing Node 14.17 or higher.
5
+ **semantic-release** is meant to be used in a CI environment as a development support tool, not as a production dependency.
6
+ Therefore, the only constraint is to run the `semantic-release` in a CI environment providing version of Node that meets our version requirement.
6
7
 
7
8
  See our [Node Support Policy](node-support-policy.md) for our long-term promise regarding Node version support.
8
9
 
9
10
  ## Recommended solution
10
11
 
11
- ### Run at least one CI job with Node >= 14.17
12
+ ### Run at least one CI job with a version of Node that meets our version requirement
12
13
 
13
- The recommended approach is to run the `semantic-release` command from a CI job running on Node 14.17 or higher.
14
- This can either be a job used by your project to test on Node >= 14.17 or a dedicated job for the release steps.
14
+ The recommended approach is to run the `semantic-release` command from a CI job running on the latest available LTS version of node.
15
+ This can either be a job used by your project to test on the latest Node LTS version or a dedicated job for the release steps.
15
16
 
16
- See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
17
+ See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details.
17
18
 
18
19
  ## Alternative solutions
19
20
 
20
- ### Use `npx`
21
+ ### Use `npx` to execute in the latest LTS version of Node
21
22
 
22
- `npx` is included with npm >= 5.2 and can be used to download the latest [Node 14 package published on npm](https://www.npmjs.com/package/node).
23
+ `npx` is included with npm >= 5.2 and can be used to download the latest [Node LTS package published on npm](https://www.npmjs.com/package/node).
23
24
  Use it to execute the `semantic-release` command.
24
25
 
25
26
  ```bash
26
- $ npx -p node@14 -c "npx semantic-release"
27
+ $ npx -p node@lts -c "npx semantic-release"
27
28
  ```
28
29
 
29
- **Note:**: See [What is npx](./FAQ.md#what-is-npx) for more details.
30
+ **Note**: See [What is npx](./FAQ.md#what-is-npx) for more details.
30
31
 
31
32
  ### Use `nvm`
32
33
 
33
- If your CI environment provides [nvm](https://github.com/creationix/nvm) you can use it to switch to Node 14.17 before running the `semantic-release` command.
34
+ If your CI environment provides [nvm](https://github.com/creationix/nvm) you can use it to switch to the latest LTS version of Node before running the `semantic-release` command.
34
35
 
35
36
  ```bash
36
- $ nvm install 14.17 && npx semantic-release
37
+ $ nvm install 'lts/*' && npx semantic-release
37
38
  ```
package/docs/support/troubleshooting.md CHANGED
@@ -65,5 +65,5 @@ To recover from that situation, do the following:
65
65
 
66
66
  1. Delete the tag(s) for the release(s) that have been lost from the git history. You can delete each tag from remote using `git push origin :[TAG NAME]`, e.g. `git push origin :v2.0.0-beta.1`. You can delete tags locally using `git tag -d [TAG NAME]`, e.g. `git tag -d v2.0.0-beta.1`.
67
67
  2. Re-create the tags locally: `git tag [TAG NAME] [COMMIT HASH]`, where `[COMMIT HASH]` is the new commit that created the release for the lost tag. E.g. `git tag v2.0.0-beta.1 abcdef0`
68
- 3. Re-create the git notes for each release tag, e.g. `git notes --ref semantic-release add -f -m '{"channels":["beta"]}' v2.0.0-beta.1`. If the release was also published in the default channel (usually `master`), then set the first channel to `null`, e.g. `git notes --ref semantic-release add -f -m '{"channels":[null, "beta"]}'
68
+ 3. Re-create the git notes for each release tag, e.g. `git notes --ref semantic-release add -f -m '{"channels":["beta"]}' v2.0.0-beta.1`. If the release was also published in the default channel (usually `master`), then set the first channel to `null`, e.g. `git notes --ref semantic-release add -f -m '{"channels":[null, "beta"]}'`
69
69
  4. Push the local notes: `git push --force origin refs/notes/semantic-release`. The `--force` is needed after the rebase. Be careful.
package/docs/usage/ci-configuration.md CHANGED
@@ -13,7 +13,7 @@ Here is a few example of the CI services that can be used to achieve this:
13
13
  - [Wercker Workflows](http://devcenter.wercker.com/docs/workflows)
14
14
  - [GoCD Pipelines](https://docs.gocd.org/current/introduction/concepts_in_go.html#pipeline).
15
15
 
16
- See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details.
16
+ See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details.
17
17
 
18
18
  ## Authentication
19
19
 
@@ -29,7 +29,7 @@ See [CI configuration recipes](../recipes/README.md#ci-configurations) for more
29
29
  | `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clearification `user:token` has to be the value of this env. |
30
30
  | `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. |
31
31
 
32
- Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-auth-ssh-keys.md).
32
+ Alternatively the Git authentication can be set up via [SSH keys](../recipes/git-hosted-services/git-auth-ssh-keys.md).
33
33
 
34
34
  ### Authentication for plugins
35
35
 
@@ -44,6 +44,6 @@ See each plugin's documentation for the environment variables required.
44
44
 
45
45
  The authentication token/credentials have to be made available in the CI service via environment variables.
46
46
 
47
- See [CI configuration recipes](../recipes/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
47
+ See [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on how to configure environment variables in your CI service.
48
48
 
49
49
  **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).
package/docs/usage/installation.md CHANGED
@@ -25,6 +25,8 @@ $ npx semantic-release
25
25
  ```
26
26
 
27
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@18`).
28
- 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
+ This way your build will not automatically use the next major **semantic-release** release that could possibly break your build.
29
+ You will have to upgrade manually when a new major version is released.
29
30
 
30
- **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.
31
+ **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.
32
+ See [What is npx](../support/FAQ.md#what-is-npx) for more details.
package/docs/usage/workflow-configuration.md CHANGED
@@ -6,7 +6,7 @@
6
6
  - Maintain multiple lines of releases in parallel
7
7
  - Work on large future releases outside the normal flow of one version increment per Git push
8
8
 
9
- See [Release workflow recipes](../recipes/README.md#release-workflow) for detailed examples.
9
+ See [Release workflow recipes](../recipes/release-workflow/README.md#release-workflow) for detailed examples.
10
10
 
11
11
  The release workflow is configured via the [branches option](./configuration.md#branches) which accepts a single or an array of branch definitions.
12
12
  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.
@@ -108,7 +108,7 @@ A project must define a minimum of 1 release branch and can have a maximum of 3.
108
108
 
109
109
  **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.
110
110
 
111
- See [publishing on distribution channels recipe](../recipes/distribution-channels.md) for a detailed example.
111
+ See [publishing on distribution channels recipe](../recipes/release-workflow/distribution-channels.md) for a detailed example.
112
112
 
113
113
  #### Pushing to a release branch
114
114
 
@@ -142,7 +142,7 @@ Maintenance branches are always considered lower than [release branches](#releas
142
142
 
143
143
  **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.
144
144
 
145
- See [publishing maintenance releases recipe](../recipes/maintenance-releases.md) for a detailed example.
145
+ See [publishing maintenance releases recipe](../recipes/release-workflow/maintenance-releases.md) for a detailed example.
146
146
 
147
147
  #### Pushing to a maintenance branch
148
148
 
@@ -171,7 +171,7 @@ A pre-release branch is characterized by the `prerelease` property that defines
171
171
 
172
172
  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.
173
173
 
174
- See [publishing pre-releases recipe](../recipes/pre-releases.md) for a detailed example.
174
+ See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md) for a detailed example.
175
175
 
176
176
  #### Pushing to a pre-release branch
177
177
 
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": "18.0.0-beta.6",
4
+ "version": "18.0.1",
5
5
  "author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
6
6
  "ava": {
7
7
  "files": [
@@ -20,11 +20,11 @@
20
20
  "Pierre Vanduynslager (https://twitter.com/@pvdlg_)"
21
21
  ],
22
22
  "dependencies": {
23
- "@semantic-release/commit-analyzer": "^8.0.0",
24
- "@semantic-release/error": "^3.0.0-beta.1",
25
- "@semantic-release/github": "^8.0.0-beta.1",
26
- "@semantic-release/npm": "^8.0.0-beta.1",
27
- "@semantic-release/release-notes-generator": "^10.0.0-beta.1",
23
+ "@semantic-release/commit-analyzer": "^9.0.2",
24
+ "@semantic-release/error": "^3.0.0",
25
+ "@semantic-release/github": "^8.0.0",
26
+ "@semantic-release/npm": "^8.0.0",
27
+ "@semantic-release/release-notes-generator": "^10.0.0",
28
28
  "aggregate-error": "^3.0.0",
29
29
  "cosmiconfig": "^7.0.0",
30
30
  "debug": "^4.0.0",
@@ -51,20 +51,20 @@
51
51
  },
52
52
  "devDependencies": {
53
53
  "ava": "3.15.0",
54
- "clear-module": "4.1.1",
55
- "codecov": "3.8.2",
54
+ "clear-module": "4.1.2",
55
+ "codecov": "3.8.3",
56
56
  "delay": "5.0.0",
57
- "dockerode": "3.3.0",
57
+ "dockerode": "3.3.1",
58
58
  "file-url": "3.0.0",
59
59
  "fs-extra": "9.1.0",
60
- "got": "11.8.2",
60
+ "got": "11.8.3",
61
61
  "js-yaml": "4.1.0",
62
62
  "mockserver-client": "5.11.2",
63
- "nock": "13.1.1",
63
+ "nock": "13.2.1",
64
64
  "nyc": "15.1.0",
65
65
  "p-retry": "4.6.1",
66
66
  "proxyquire": "2.1.3",
67
- "sinon": "11.1.1",
67
+ "sinon": "12.0.1",
68
68
  "stream-buffers": "3.0.2",
69
69
  "tempy": "1.0.1",
70
70
  "xo": "0.29.1"
package/docs/recipes/README.md DELETED
@@ -1,18 +0,0 @@
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
- - [GitHub Actions](github-actions.md)
8
- - [Jenkins CI](jenkins-ci.md)
9
-
10
- ## Git hosted services
11
- - [Git authentication with SSH keys](git-auth-ssh-keys.md)
12
-
13
- ## Release workflow
14
- - [Publishing on distribution channels](distribution-channels.md)
15
- - [Publishing maintenance releases](maintenance-releases.md)
16
- - [Publishing pre-releases](pre-releases.md)
17
-
18
- ## Package managers and languages