semantic-release 25.0.5 → 25.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/README.md +36 -30
  2. package/bin/semantic-release.js +1 -1
  3. package/lib/definitions/errors.js +38 -33
  4. package/lib/hide-sensitive.js +14 -1
  5. package/package.json +20 -15
  6. package/docs/README.md +0 -7
  7. package/docs/developer-guide/README.md +0 -5
  8. package/docs/developer-guide/js-api.md +0 -294
  9. package/docs/developer-guide/plugin.md +0 -284
  10. package/docs/developer-guide/shareable-configuration.md +0 -1
  11. package/docs/extending/README.md +0 -4
  12. package/docs/extending/plugins-list.md +0 -233
  13. package/docs/extending/shareable-configurations-list.md +0 -22
  14. package/docs/recipes/ci-configurations/README.md +0 -7
  15. package/docs/recipes/ci-configurations/circleci-workflows.md +0 -49
  16. package/docs/recipes/ci-configurations/github-actions.md +0 -136
  17. package/docs/recipes/ci-configurations/gitlab-ci.md +0 -98
  18. package/docs/recipes/ci-configurations/jenkins-ci.md +0 -61
  19. package/docs/recipes/ci-configurations/travis.md +0 -97
  20. package/docs/recipes/git-hosted-services/README.md +0 -3
  21. package/docs/recipes/git-hosted-services/git-auth-ssh-keys.md +0 -166
  22. package/docs/recipes/release-workflow/README.md +0 -5
  23. package/docs/recipes/release-workflow/distribution-channels.md +0 -117
  24. package/docs/recipes/release-workflow/maintenance-releases.md +0 -157
  25. package/docs/recipes/release-workflow/pre-releases.md +0 -197
  26. package/docs/support/FAQ.md +0 -253
  27. package/docs/support/README.md +0 -7
  28. package/docs/support/git-version.md +0 -4
  29. package/docs/support/node-support-policy.md +0 -21
  30. package/docs/support/node-version.md +0 -38
  31. package/docs/support/resources.md +0 -22
  32. package/docs/support/troubleshooting.md +0 -70
  33. package/docs/usage/README.md +0 -9
  34. package/docs/usage/ci-configuration.md +0 -50
  35. package/docs/usage/configuration.md +0 -206
  36. package/docs/usage/getting-started.md +0 -8
  37. package/docs/usage/installation.md +0 -51
  38. package/docs/usage/plugins.md +0 -105
  39. package/docs/usage/shareable-configurations.md +0 -7
  40. package/docs/usage/workflow-configuration.md +0 -199
@@ -1,197 +0,0 @@
1
- # Publishing pre-releases
2
-
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
-
5
- This example uses the **semantic-release** default configuration:
6
-
7
- - [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
8
- - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
9
-
10
- ## Initial release
11
-
12
- We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit`. When pushing that commit, on `master`/`main` **semantic-release** will release the version `1.0.0` and make it available on the default distribution channel which is the dist-tag `@latest` for npm.
13
-
14
- The Git history of the repository is:
15
-
16
- ```
17
- * feat: initial commit # => v1.0.0 on @latest
18
- ```
19
-
20
- ## Working on a future release
21
-
22
- We now decide to work on a future major release, which will be composed of multiple features, some of them being breaking changes. We want to publish our package for each new feature developed for test purpose, however we do not want to increment our package version or make it available to our users until all the features are developed and tested.
23
-
24
- To implement that workflow we can create the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `2.0.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `1.0.0`.
25
-
26
- The Git history of the repository is now:
27
-
28
- ```
29
- * feat: initial commit # => v1.0.0 on @latest
30
- | \
31
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
32
- ```
33
-
34
- We can continue to work on our future release by committing and pushing other features or bug fixes on the `beta` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@beta`, which allow us to run our integration tests.
35
-
36
- With another feature, the Git history of the repository is now:
37
-
38
- ```
39
- * feat: initial commit # => v1.0.0 on @latest
40
- | \
41
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
42
- | * feat: second feature # => v2.0.0-beta.2 on @beta
43
- ```
44
-
45
- ## Releasing a bug fix on the default distribution channel
46
-
47
- In the meantime we can also continue to commit changes and release updates to our users.
48
-
49
- For example, we can commit a bug fix with the message `fix: a fix` to `master`/`main`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
50
-
51
- The Git history of the repository is now:
52
-
53
- ```
54
- * feat: initial commit # => v1.0.0 on @latest
55
- | \
56
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
57
- | * feat: second feature # => v2.0.0-beta.2 on @beta
58
- * | fix: a fix # => v1.0.1 on @latest
59
- ```
60
-
61
- ## Working on another future release
62
-
63
- We now decide to work on another future major release, in parallel of the beta one, which will also be composed of multiple features, some of them being breaking changes.
64
-
65
- To implement that workflow we can create the branch `alpha` from the branch `beta` and commit our first feature there. When pushing that commit, **semantic-release** will publish the pre-release version `3.0.0-alpha.1` on the dist-tag `@alpha`. That allow us to run integration tests by installing our module with `npm install example-module@alpha`. Other users installing with `npm install example-module` will still receive the version `1.0.1`.
66
-
67
- The Git history of the repository is now:
68
-
69
- ```
70
- * feat: initial commit # => v1.0.0 on @latest
71
- | \
72
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
73
- | * feat: second feature # => v2.0.0-beta.2 on @beta
74
- * | fix: a fix # => v1.0.1 on @latest
75
- | | \
76
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
77
- ```
78
-
79
- We can continue to work on our future release by committing and pushing other features or bug fixes on the `alpha` branch. With each push, **semantic-release** will publish a new pre-release on the dist-tag `@alpha`, which allow us to run our integration tests.
80
-
81
- With another feature, the Git history of the repository is now:
82
-
83
- ```
84
- * feat: initial commit # => v1.0.0 on @latest
85
- | \
86
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
87
- | * feat: second feature # => v2.0.0-beta.2 on @beta
88
- * | fix: a fix # => v1.0.1 on @latest
89
- | | \
90
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
91
- | | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
92
- ```
93
-
94
- ## Publishing the 2.0.0 beta release to the default distribution channel
95
-
96
- Once we've developed and pushed all the feature we want to include in the future version `2.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
97
-
98
- To do so we need to merge our changes made on `beta` into `master`/`main`. As `beta` and `master`/`main` branches have diverged, this merge might require to resolve conflicts.
99
-
100
- Once the conflicts are resolved and the merge commit is pushed to `master`/`main`, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
101
-
102
- The Git history of the repository is now:
103
-
104
- ```
105
- * feat: initial commit # => v1.0.0 on @latest
106
- | \
107
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
108
- | * feat: second feature # => v2.0.0-beta.2 on @beta
109
- * | fix: a fix # => v1.0.1 on @latest
110
- | | \
111
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
112
- | | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
113
- | /| |
114
- * | | Merge branch beta into master/main # => v2.0.0 on @latest
115
- ```
116
-
117
- ## Publishing the 3.0.0 alpha release to the beta distribution channel
118
-
119
- Now that we published our the version `2.0.0` that was previously in beta, we decide to promote the version `3.0.0` in alpha to beta.
120
-
121
- To do so we need to merge our changes made on `alpha` into `beta`. There should be no conflict as `alpha` is strictly ahead of `master`/`main`.
122
-
123
- Once the merge commit is pushed to `beta`, **semantic-release** will publish the pre-release version `3.0.0-beta.1` on the dist-tag `@beta`, which allow us to run our integration tests.
124
-
125
- The Git history of the repository is now:
126
-
127
- ```
128
- * feat: initial commit # => v1.0.0 on @latest
129
- | \
130
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
131
- | * feat: second feature # => v2.0.0-beta.2 on @beta
132
- * | fix: a fix # => v1.0.1 on @latest
133
- | | \
134
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
135
- | | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
136
- | /| |
137
- * | | Merge branch beta into master/main # => v2.0.0 on @latest
138
- | | /|
139
- | * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
140
- ```
141
-
142
- ## Publishing the 3.0.0 beta release to the default distribution channel
143
-
144
- Once we've developed and pushed all the feature we want to include in the future version `3.0.0` in the `beta` branch and all our tests are successful we can release it to our users.
145
-
146
- To do so we need to merge our changes made on `beta` into `master`/`main`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
147
-
148
- Once the conflicts are resolved and the merge commit is pushed to `master` or `main`, **semantic-release** will release the version `3.0.0` on the dist-tag `@latest`.
149
-
150
- The Git history of the repository is now:
151
-
152
- ```
153
- * feat: initial commit # => v1.0.0 on @latest
154
- | \
155
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
156
- | * feat: second feature # => v2.0.0-beta.2 on @beta
157
- * | fix: a fix # => v1.0.1 on @latest
158
- | | \
159
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
160
- | | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
161
- | /| |
162
- * | | Merge branch beta into master/main # => v2.0.0 on @latest
163
- | | /|
164
- | * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
165
- | /| |
166
- * | | Merge branch beta into master/main # => v3.0.0 on @latest
167
- ```
168
-
169
- ## Working on a third future release
170
-
171
- We can now start to work on a new future major release, version `4.0.0`, on the `@beta` distribution channel.
172
-
173
- To do so we first need to update the `beta` branch with all the changes from `master` or `main` (the commits `fix: a fix`). As `beta` and `master`/`main` branches have diverged, this merge might require to resolve conflicts.
174
-
175
- We can now commit our new feature on `beta`. When pushing that commit, **semantic-release** will publish the pre-release version `3.1.0-beta.1` on the dist-tag `@beta`. That allow us to run integration tests by installing our module with `npm install example-module@beta`. Other users installing with `npm install example-module` will still receive the version `3.0.0`.
176
-
177
- The Git history of the repository is now:
178
-
179
- ```
180
- * feat: initial commit # => v1.0.0 on @latest
181
- | \
182
- | * feat: first feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0-beta.1 on @beta
183
- | * feat: second feature # => v2.0.0-beta.2 on @beta
184
- * | fix: a fix # => v1.0.1 on @latest
185
- | | \
186
- | | * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
187
- | | * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
188
- | /| |
189
- * | | Merge branch beta into master/main # => v2.0.0 on @latest
190
- | | /|
191
- | * | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
192
- | /| |
193
- * | | Merge branch beta into master/main # => v3.0.0 on @latest
194
- | \| |
195
- | * | Merge branch master/main into beta
196
- | * | feat: new feature # => v3.1.0-beta.1 on @beta
197
- ```
@@ -1,253 +0,0 @@
1
- # Frequently Asked Questions
2
-
3
- ## Why is the `package.json`’s version not updated in my repository?
4
-
5
- ### It is not needed for semantic-release to do its job
6
-
7
- [`@semantic-release/npm`](https://github.com/semantic-release/npm) takes care of updating the `package.json`’s version before publishing to [npm](https://www.npmjs.com) based on the previous version that was tracked as a git tag.
8
- By default, only the published package will contain the version, which is the only place where it is _really_ required, but the updated `package.json` will not be pushed to the Git repository.
9
- A git tag is added to track the new version, so committing the version is not necessary for semantic-release to pick up from there for the next release.
10
-
11
- ### It can lead to confusion
12
-
13
- Some teams find value in being able to reference the repository to determine the current latest version available for the published package.
14
- Unfortunately, there are some failure scenarios where semantic-release might leave the committed version in the repository out of sync with the version that exists in the registry.
15
- The best way to determine available versions is to consult the registry that your package is published to, since it is the actual source of truth.
16
- The [npm CLI](https://docs.npmjs.com/cli/npm) can be used to consult the registry with the following command:
17
-
18
- ```shell
19
- npm dist-tags ls <package-name>
20
- ```
21
-
22
- When not committing updates to the version, a value that follows the semver guidelines is still required for the `version` property within the `package.json`.
23
- To make it clear to contributors that the version is not kept up to date, we recommend using a value like `0.0.0-development` or `0.0.0-semantically-released`.
24
-
25
- ### Making commits during the release process adds significant complexity
26
-
27
- While the [`@semantic-release/git`](https://github.com/semantic-release/git) enables committing such changes and pushing them back to the repository as part of a release, we strongly recommend against this practice.
28
-
29
- Making commits and pushing them back to the repository adds significant additional complexity to your release process that can be avoided:
30
-
31
- - Branch protection configuration must account for allowing the release user account to bypass restrictions enforced for human contributors, which might require elevating the access level of the release user beyond what would otherwise be desired/considered secure.
32
- - Pre-commit hooks configured for a project, which is a popular practice when enabling [commitlint](https://commitlint.js.org/) through [husky](https://typicode.github.io/husky/), for example, must be accounted for in the release process.
33
- (We recommend disabling tools like this for automated commits, but you need to decide what is appropriate for your project)
34
-
35
- ### There are valid reasons to commit during a release
36
-
37
- If you make your npm package available directly via a GitHub repository rather than publishing to a registry, for example, making a commit and pushing to the repository is a necessary step.
38
- In such a case you will want to use [`@semantic-release/git`](https://github.com/semantic-release/git) to coordinate the commit and push.
39
- You can set the project to `"private": true,` within your `package.json` to [prevent publishing to the registry](https://docs.npmjs.com/cli/v10/using-npm/registry#how-can-i-prevent-my-package-from-being-published-in-the-official-registry).
40
-
41
- However, if you are choosing to follow this path because you can't use the official npm registry and don't want to manage your own registry, consider [publishing to GitHub packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry) instead.
42
-
43
- ## Should release notes be committed to a `CHANGELOG.md` in my repository during a release?
44
-
45
- [`@semantic-release/changelog`](https://github.com/semantic-release/changelog) can be used to add release notes to a `CHANGELOG.md` file within your repository as part of each release.
46
- Committing changes to a `CHANGELOG.md` or similar file introduces the same [complexities](#making-commits-during-the-release-process-adds-significant-complexity) as committing an updated version within a `package.json` file.
47
- In addition, the release notes that would be added to a changelog file are likely redundant with the release notes added as GitHub releases, if that is also configured for your project (enabled by default).
48
-
49
- Before deciding that a changelog file is necessary for your project, please consider whether the added complexity is worth it when GitHub releases (or similar for your host, if not GitHub) might accomplish the same goal.
50
- It could also be worth considering whether having a `CHANGELOG.md` in your repository that only contains a link to the project's GitHub releases could be an acceptable middle ground.
51
-
52
- ## How can I use a npm build script that requires the `package.json`’s version ?
53
-
54
- The `package.json`’s version will be updated by the `semantic-release` command just before publishing to [npm](https://www.npmjs.com), therefore it won't be available for scripts ran before the `semantic-release` command.
55
-
56
- As the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin uses the [npm CLI](https://docs.npmjs.com/cli/npm) to update the `package.json` version and publish the package, all [npm hook scripts](https://docs.npmjs.com/misc/scripts#description) will be executed.
57
-
58
- You can run your build script in:
59
-
60
- - the `prepublishOnly` or `prepack` hook so it will be executed during the `publish` step of `@semantic-release/npm`
61
- - the `postversion` hook so it will be executed during the `prepare` step of `@semantic-release/npm`, which allow for example to update files before committing them with the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin
62
-
63
- If using npm hook scripts is not possible, and alternative solution is to [`@semantic-release/exec`](https://github.com/semantic-release/exec) plugin to run your script in the `prepare` step:
64
-
65
- ```json
66
- {
67
- "plugins": [
68
- "@semantic-release/commit-analyzer",
69
- "@semantic-release/release-notes-generator",
70
- "@semantic-release/npm",
71
- [
72
- "@semantic-release/exec",
73
- {
74
- "prepareCmd": "./my-build-script.sh ${nextRelease.version}"
75
- }
76
- ]
77
- ]
78
- }
79
- ```
80
-
81
- ## Is there a way to preview which version would currently get published?
82
-
83
- 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.
84
-
85
- ## Can I use semantic-release to publish non-JavaScript packages?
86
-
87
- Yes, **semantic-release** is a Node CLI application, but it can be used to publish any type of packages.
88
-
89
- To publish a non-Node package (without a `package.json`) you would need to:
90
-
91
- - Use a [global](../usage/installation.md#global-installation) **semantic-release** installation
92
- - Set **semantic-release** [options](../usage/configuration.md#options) via [CLI arguments or `.rc` file](../usage/configuration.md#configuration)
93
- - 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
94
-
95
- See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
96
-
97
- 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.
98
-
99
- 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.
100
-
101
- Here is a basic example to create [GitHub releases](https://help.github.com/articles/about-releases) and use a shell command to publish:
102
-
103
- ```json
104
- {
105
- "plugins": [
106
- "@semantic-release/commit-analyzer",
107
- "@semantic-release/release-notes-generator",
108
- "@semantic-release/github",
109
- [
110
- "@semantic-release/exec",
111
- {
112
- "prepareCmd": "set-version ${nextRelease.version}",
113
- "publishCmd": "publish-package"
114
- }
115
- ]
116
- ]
117
- }
118
- ```
119
-
120
- **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.
121
-
122
- See the [package managers and languages recipes](../recipes/release-workflow/README.md#package-managers-and-languages) for more details on specific project types and the [available plugins list](../extending/plugins-list.md) to see if there are community-supported plugins already available for the stack you are interested in.
123
-
124
- ## Can I use semantic-release with any CI service?
125
-
126
- Yes, **semantic-release** can be used with any CI service, as long as it provides:
127
-
128
- - A way to set [authentication](../usage/ci-configuration.md#authentication) via environment variables
129
- - 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)
130
-
131
- See the [CI configuration recipes](../recipes/release-workflow/README.md#ci-configurations) for more details on specific CI environments.
132
-
133
- ## Can I run semantic-release on my local machine rather than on a CI server?
134
-
135
- 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:
136
-
137
- ```bash
138
- $ NPM_TOKEN=<your_npm_token> GH_TOKEN=<your_github_token> npx semantic-release --no-ci
139
- ```
140
-
141
- However this is not the recommended approach, as running unit and integration tests on an independent machine before publishing software is a crucial part of the release workflow.
142
-
143
- ## Can I use semantic-release with GitLab?
144
-
145
- Yes, with the [`@semantic-release/gitlab-config`](https://github.com/semantic-release/gitlab-config) shareable configuration.
146
-
147
- See the [GitLab CI recipes](../recipes/ci-configurations/gitlab-ci.md#using-semantic-release-with-gitlab-ci) for the CI configuration.
148
-
149
- ## Can I use semantic-release with any Git hosted environment?
150
-
151
- 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).
152
-
153
- 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.
154
-
155
- ## Can I skip the release to the npm registry?
156
-
157
- Yes, the publishing to the npm registry can be disabled with the [`npmPublish`](https://github.com/semantic-release/npm#options) option of the [`@semantic-release/npm`](https://github.com/semantic-release/npm) plugin. In addition the [`tarballDir`](https://github.com/semantic-release/npm#options) option allow to generate the package tarball in order to publish it to your repository with the [`@semantic-release/git`](https://github.com/semantic-release/git) or to a [GitHub release](https://help.github.com/articles/about-releases) with the [`@semantic-release/github`](https://github.com/semantic-release/github) plugin.
158
-
159
- See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#semantic-releasenpm) plugin documentation for more details.
160
-
161
- ## How can I revert a release?
162
-
163
- If you have introduced a breaking bug in a release you have 2 options:
164
-
165
- - If you have a fix immediately ready, commit and push it (or merge it via a pull request) to the release branch
166
- - Otherwise, [revert the commit](https://git-scm.com/docs/git-revert) that introduced the bug and push the revert commit (or merge it via a pull request) to the release branch
167
-
168
- In both cases **semantic-release** will publish a new release, so your package users will get the fixed/reverted version.
169
-
170
- Depending on the package manager you are using, you might be able to un-publish or deprecate a release, in order to prevent users from downloading it by accident. For example, npm allows you to [un-publish](https://docs.npmjs.com/cli/unpublish) [within 72 hours](https://www.npmjs.com/policies/unpublish) after release. You may also [deprecate](https://docs.npmjs.com/cli/deprecate) a release if you would rather avoid un-publishing.
171
-
172
- In any case **do not remove the Git tag associated with the buggy version**, otherwise **semantic-release** will later try to republish that version. Publishing a version after un-publishing is not supported by most package managers.
173
-
174
- **Note**: If you are using the default [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) be aware that it uses a different revert commit format than the standard one created by [git revert](https://git-scm.com/docs/git-revert), contrary to what is [claimed in the convention](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). Therefore, if you revert a commit with [`git revert`](https://git-scm.com/docs/git-revert), use the [`--edit` option](https://git-scm.com/docs/git-revert#git-revert---edit) to format the message according to the [Angular revert commit message format](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#revert). See [conventional-changelog/conventional-changelog#348](https://github.com/conventional-changelog/conventional-changelog/issues/348) for more details.
175
-
176
- ## Can I use `.npmrc` options?
177
-
178
- Yes, all the [npm configuration options](https://docs.npmjs.com/misc/config) are supported via the [`.npmrc`](https://docs.npmjs.com/files/npmrc) file at the root of your repository.
179
-
180
- See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#npm-configuration) plugin documentation for more details.
181
-
182
- ## How can I set the access level of the published npm package?
183
-
184
- The [npm `access` option](https://docs.npmjs.com/misc/config#access) can be set in the [`.npmrc`](https://docs.npmjs.com/files/npmrc) file at the root of your repository:
185
-
186
- ```rc
187
- access=public
188
- ```
189
-
190
- Or with the `publishConfig.access` key in your project's `package.json`:
191
-
192
- ```json
193
- {
194
- "publishConfig": {
195
- "access": "public"
196
- }
197
- }
198
- ```
199
-
200
- ## Can I manually trigger the release of a specific version?
201
-
202
- You can trigger a release by pushing to your Git repository. You deliberately cannot trigger a _specific_ version release, because this is the whole point of semantic-release.
203
-
204
- ## Can I exclude commits from the analysis?
205
-
206
- Yes, every commits that contains `[skip release]` or `[release skip]` in their message will be excluded from the commit analysis and won't participate in the release type determination.
207
-
208
- ## How can I change the type of commits that trigger a release?
209
-
210
- By default **semantic-release** uses the [Angular Commit Message Conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines) and triggers releases based on the following rules:
211
-
212
- | Commit | Release type |
213
- | --------------------------- | -------------------------- |
214
- | Commit with breaking change | ~~Major~~ Breaking release |
215
- | Commit with type `feat` | ~~Minor~~ Feature release |
216
- | Commit with type `fix` | Patch release |
217
- | Commit with type `perf` | Patch release |
218
-
219
- See the [`@semantic-release/npm`](https://github.com/semantic-release/npm#npm-configuration) plugin documentation for more details.
220
-
221
- This is fully customizable with the [`@semantic-release/commit-analyzer`](https://github.com/semantic-release/commit-analyzer) plugin's [`release-rules` option](https://github.com/semantic-release/commit-analyzer#release-rules).
222
-
223
- ## Is it _really_ a good idea to release on every push?
224
-
225
- It is indeed a great idea because it _forces_ you to follow best practices. If you don’t feel comfortable releasing every feature or fix on your `master`/`main` you might not treat your `master`/`main` branch as intended.
226
-
227
- From [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/index.html):
228
-
229
- > Branching is a core concept in Git, and the entire GitHub Flow is based upon it. There's only one rule: anything in the master/main branch is always deployable.
230
-
231
- If you need more control over the timing of releases, see [Triggering a release](../../README.md#triggering-a-release) for different options.
232
-
233
- **Note**: Only the codebase changes altering the published package will trigger a release (for example new features, bug fixes or performance improvements would trigger a release while refactoring or changing code style would not). See [How can I change the type of commits that trigger a release?](#how-can-i-change-the-type-of-commits-that-trigger-a-release) for more details.
234
-
235
- ## Can I set the initial release version of my package to `0.0.1`?
236
-
237
- This is not supported by semantic-release. [Semantic Versioning](https://semver.org/) rules apply differently to major version zero and supporting those differences is out of scope and not one of the goals of the semantic-release project.
238
-
239
- 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).
240
-
241
- 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`.
242
-
243
- ## Can I trust semantic-release with my releases?
244
-
245
- **semantic-release** has a full unit and integration test suite that tests `npm` publishes against the [verdaccio](https://www.npmjs.com/package/verdaccio).
246
-
247
- 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).
248
-
249
- ## What is npx?
250
-
251
- [`npx`](https://www.npmjs.com/package/npx) – short for "npm exec" – is a CLI to find and execute npm binaries within the local `node_modules` folder or in the $PATH. If a binary can't be located npx will download the required package and execute it from its cache location.
252
- The tool is bundled with [npm](https://www.npmjs.com/package/npm) >= 5.2, or can be installed via `npm install -g npx`.
253
- For more details and motivation read the [introductory blog post](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) by [@zkat](https://github.com/zkat).
@@ -1,7 +0,0 @@
1
- # Support
2
-
3
- - [Resources](resources.md) - Videos, articles and tutorials
4
- - [Frequently Asked Questions](FAQ.md)
5
- - [Troubleshooting](troubleshooting.md)
6
- - [Node version requirement](node-version.md)
7
- - [Node Support Policy](node-support-policy.md)
@@ -1,4 +0,0 @@
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.
@@ -1,21 +0,0 @@
1
- # Node Support Policy
2
-
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.
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.
7
-
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.
10
-
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.
15
-
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.
19
-
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.
@@ -1,38 +0,0 @@
1
- # Node version requirement
2
-
3
- **semantic-release** is written using the latest [ECMAScript 2017](https://www.ecma-international.org/publications/standards/Ecma-262.htm) features, without transpilation which **requires Node version 22.14.0 or higher**.
4
-
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.
7
-
8
- See our [Node Support Policy](node-support-policy.md) for our long-term promise regarding Node version support.
9
-
10
- ## Recommended solution
11
-
12
- ### Run at least one CI job with a version of Node that meets our version requirement
13
-
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.
16
-
17
- See [CI configuration](../usage/ci-configuration.md) and [CI configuration recipes](../recipes/ci-configurations/README.md#ci-configurations) for more details.
18
-
19
- ## Alternative solutions
20
-
21
- ### Use `npx` to execute in the latest LTS version of Node
22
-
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).
24
- Use it to execute the `semantic-release` command.
25
-
26
- ```bash
27
- $ npx -p node@v24 -c "npx semantic-release"
28
- ```
29
-
30
- **Note**: See [What is npx](./FAQ.md#what-is-npx) for more details.
31
-
32
- ### Use `nvm`
33
-
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.
35
-
36
- ```bash
37
- $ nvm install 'lts/*' && npx semantic-release
38
- ```
@@ -1,22 +0,0 @@
1
- # Resources
2
-
3
- ## Videos
4
-
5
- - ["Introducing Reliable Dependency and Release Management for npm Packages" - Gregor Martynus](https://www.youtube.com/watch?v=R2RJWLcfzwc)
6
- - ["Kill all humans" - Jan Lehnardt](https://www.youtube.com/watch?v=ZXyx_1kN1L8&t=2s)
7
- - ["Publishing JavaScript Packages" - JavaScript Air](https://javascriptair.com/episodes/2016-07-20)
8
- - ["Managing Dependencies like a boss 😎" - JavaScript Air](https://javascriptair.com/episodes/2016-08-17)
9
- - ["Dependency Hell Just Froze Over" - Stephan Bönnemann](https://www.youtube.com/watch?v=PA139CERNbc)
10
- - ["semantic-release Q&A with Kent C. Dodds"](https://www.youtube.com/watch?v=g6y3DnhkjrI)
11
- - ["We fail to follow SemVer – and why it needn’t matter" - Stephan Bönnemann](https://www.youtube.com/watch?v=tc2UgG5L7WM)
12
-
13
- ## Articles
14
-
15
- - ["Introduction to SemVer" - Irina Gebauer](https://blog.greenkeeper.io/introduction-to-semver-d272990c44f2)
16
- - ["Introduction to Semantic Release" - liv](https://blog.greenkeeper.io/introduction-to-semantic-release-33f73b117c8)
17
- - ["Series - Semantic Release Automation" - Abdelrahman Wahdan](https://dev.to/abdelrahmanahmed/semantic-release-and-how-to-automate-it-part-1-4pa2)
18
- - ["Explain semantic release and how to use it on GitLab pipeline"](https://regoo707.medium.com/auto-bump-apps-versions-and-releases-using-gitlab-pipeline-e32f1d7fa3ee)
19
-
20
- ## Tutorials
21
-
22
- - ["How to Write a JavaScript Library - Automating Releases with semantic-release" – egghead.io](https://egghead.io/lessons/javascript-automating-releases-with-semantic-release)
@@ -1,70 +0,0 @@
1
- # Troubleshooting
2
-
3
- ## You do not have permission to publish 'package-name'
4
-
5
- When running semantic-release you might encounter the following error:
6
-
7
- ```bash
8
- npm ERR! publish Failed PUT 403
9
- npm ERR! code E403
10
- npm ERR! You do not have permission to publish "<package-name>". Are you logged in as the correct user? : <package-name>
11
- ```
12
-
13
- This is most likely related to a misconfiguration of the [npm registry authentication](https://github.com/semantic-release/npm#npm-registry-authentication) or to your user [missing permission](https://docs.npmjs.com/cli/team) for publishing.
14
-
15
- It might also happen if the package name you are trying to publish already exists (in the case of npm, you may be trying to publish a new version of a package that is not yours, hence the permission error).
16
-
17
- To verify if your package name is available you can use [npm-name-cli](https://github.com/sindresorhus/npm-name-cli):
18
-
19
- ```bash
20
- $ npm install --global npm-name-cli
21
- $ npm-name <package-name>
22
- ```
23
-
24
- If the package name is not available, change it in your `package.json` or consider using an [npm scope](https://docs.npmjs.com/misc/scope).
25
-
26
- ## Squashed commits are ignored by **semantic-release**
27
-
28
- **semantic-release** parses commits according to a [commit message convention](https://github.com/semantic-release/semantic-release#commit-message-format) to figure out how they affect the codebase. Commits that doesn't follow the project's commit message convention are simply ignored.
29
-
30
- When [squashing commits](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History#_squashing) most Git tools will by default generate a new commit message with a summary of the squashed commits. This commit message will most likely not be compliant with the project's commit message convention and therefore will be ignored by **semantic-release**.
31
-
32
- When squashing commits make sure to rewrite the resulting commit message to be compliant with the project's commit message convention.
33
-
34
- **Note**: if the resulting squashed commit encompasses multiple changes (for example multiple unrelated features or fixes) then it's probably not a good idea to squash those commits together. A commit should contain exactly one self-contained functional change and a functional change should be contained in exactly one commit. See [atomic commits](https://en.wikipedia.org/wiki/Atomic_commit).
35
-
36
- ## `reference already exists` error when pushing tag
37
-
38
- **semantic-release** read [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging) that are present in the history of your release branch in order to determine the last release published. Then it determines the next version to release based on the commits pushed since then and create the corresponding tag.
39
- If a tag with the name already in your repository, Git will throw and error as tags must be unique across the repository.
40
- This situation happens when you have a version tag identical to the new one **semantic-release** is trying to create that is not in the history of the current branch.
41
-
42
- If an actual release with that version number was published you need to merge all the commits up to that release into your release branch.
43
-
44
- If there is no published release with that version number, the tag must be deleted.
45
-
46
- ```bash
47
- # Verify if the commit exists in the repository
48
- $ git rev-list -1 <tag name>
49
- # If a commit sha is returned, then the tag exists
50
-
51
- # Verify the branches having the tagged commit in their history
52
- $ git branch --contains <tag name>
53
-
54
- # Delete the tag
55
- $ git tag -d <tag name>
56
- $ git push origin :refs/tags/<tag name>
57
- ```
58
-
59
- ## release not found release branch after `git push --force`
60
-
61
- **semantic-release** is using both [git tags](https://git-scm.com/docs/git-tag) and [git notes](https://git-scm.com/docs/git-notes) to store information about which releases happened in which branch.
62
-
63
- After a git history rewrite due to a `git push --force`, the git tags and notes referencing the commits that were rewritten are lost.
64
-
65
- To recover from that situation, do the following:
66
-
67
- 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 -d :[TAG NAME]`, e.g. `git push origin -d :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`.
68
- 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`
69
- 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`/`main`), then set the first channel to `null`, e.g. `git notes --ref semantic-release add -f -m '{"channels":[null, "beta"]}'`
70
- 4. Push the local notes: `git push --force origin refs/notes/semantic-release`. The `--force` is needed after the rebase. Be careful.
@@ -1,9 +0,0 @@
1
- # Usage
2
-
3
- - [Getting started](getting-started.md#getting-started)
4
- - [Installation](installation.md#installation)
5
- - [CI Configuration](ci-configuration.md#ci-configuration)
6
- - [Configuration](configuration.md#configuration)
7
- - [Plugins](plugins.md)
8
- - [Workflow configuration](workflow-configuration.md)
9
- - [Shareable configurations](shareable-configurations.md)