semantic-release 23.0.8 → 23.1.0

package/README.md

@@ -73,7 +73,7 @@ This way no human is directly involved in the release process and the releases a
 
 ### Triggering a release
 
-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.
+For each new commit added to one of the release branches (for example: `master`, `main`, `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.
 
 **semantic-release** offers various ways to control the timing, the content and the audience of published releases.
 See example workflows in the following recipes:

package/docs/developer-guide/js-api.md

@@ -16,6 +16,7 @@ try {
       branches: [
         "+([0-9])?(.{+([0-9]),x}).x",
         "master",
+        "main",
         "next",
         "next-major",
         { name: "beta", prerelease: true },

package/docs/extending/plugins-list.md

@@ -133,10 +133,6 @@
   - `verifyConditions`: Verify the environment variable `PYPI_TOKEN` and installation of build tools
   - `prepare`: Update the version in `setup.cfg` and create the distribution packages
   - `publish`: Publish the python package to a repository (default: pypi)
-- [semantic-release-helm](https://github.com/m1pl/semantic-release-helm)
-  - `verifyConditions`: Validate configuration and (if present) credentials
-  - `prepare`: Update version and appVersion in `Chart.yaml`
-  - `publish`: Publish the chart to a registry (if configured)
 - [semantic-release-codeartifact](https://github.com/ryansonshine/semantic-release-codeartifact)
   - `verifyConditions`: Validate configuration, get AWS CodeArtifact authentication and repository, validate `publishConfig` or `.npmrc` (if they exist), then pass the configuration to the associated plugins.
 - [semantic-release-telegram](https://github.com/pustovitDmytro/semantic-release-telegram)

package/docs/recipes/ci-configurations/github-actions.md

@@ -4,7 +4,7 @@
 
 The [Authentication](../../usage/ci-configuration.md#authentication) environment variables can be configured with [Secret Variables](https://docs.github.com/en/actions/reference/encrypted-secrets).
 
-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.
+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://docs.github.com/en/actions/security-guides/automatic-token-authentication) 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.
 
 ## npm provenance
 
@@ -19,7 +19,7 @@ Find more detail about configuring npm to publish with provenance through semant
 
 ### `.github/workflows/release.yml` configuration for Node projects
 
-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.
+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/main` branch.
 See [Configuring a Workflow](https://help.github.com/en/articles/configuring-a-workflow) for additional configuration options.
 
 ```yaml
@@ -27,7 +27,7 @@ name: Release
 on:
   push:
     branches:
-      - master
+      - master # or main
 
 permissions:
   contents: read # for checkout
@@ -61,20 +61,23 @@ jobs:
         run: npx semantic-release
 ```
 
-## Pushing `package.json` changes to a `master` branch
+## Pushing `package.json` changes to your repository
 
-To keep `package.json` updated in the `master` branch, [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used.
+If you choose to commit changes to your `package.json` [against our recommendation](../../support/FAQ.md#making-commits-during-the-release-process-adds-significant-complexity), the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used.
 
-**Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch. It is **not** advised to mitigate this limitation by overriding an automatically populated `GITHUB_TOKEN` variable with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), as it poses a security risk. Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant. One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks.
+**Note**: Automatically populated `GITHUB_TOKEN` cannot be used if branch protection is enabled for the target branch.
+It is **not** advised to mitigate this limitation by overriding an automatically populated `GITHUB_TOKEN` variable with a [Personal Access Tokens](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line), as it poses a security risk.
+Since Secret Variables are available for Workflows triggered by any branch, it becomes a potential vector of attack, where a Workflow triggered from a non-protected branch can expose and use a token with elevated permissions, yielding branch protection insignificant.
+One can use Personal Access Tokens in trusted environments, where all developers should have the ability to perform administrative actions in the given repository and branch protection is enabled solely for convenience purposes, to remind about required reviews or CI checks.
 
 If the risk is acceptable, some extra configuration is needed. The [actions/checkout `persist-credentials`](https://github.com/marketplace/actions/checkout#usage) option needs to be `false`, otherwise the generated `GITHUB_TOKEN` will interfere with the custom one. Example:
 
 ```yaml
 - name: Checkout
-    uses: actions/checkout@v2
-    with:
-      fetch-depth: 0
-      persist-credentials: false # <--- this
+  uses: actions/checkout@v2
+  with:
+    fetch-depth: 0
+    persist-credentials: false # <--- this
 ```
 
 ## Trigger semantic-release on demand

package/docs/recipes/ci-configurations/gitlab-ci.md

@@ -58,7 +58,7 @@ This example is a minimal configuration for **semantic-release** with a build ru
 **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.
 
 ```yaml
-# The release pipeline will run only on the master branch a commit is triggered
+# The release pipeline will run only on the master/main branch a commit is triggered
 stages:
   - release
 
@@ -71,7 +71,7 @@ release:
   script:
     - semantic-release
   rules:
-    - if: $CI_COMMIT_BRANCH == "master"
+    - if: $CI_COMMIT_BRANCH == "master" # or main
 
 release:
   image: node:12-buster-slim
@@ -82,7 +82,7 @@ release:
   script:
     - semantic-release
   rules:
-    - if: $CI_COMMIT_BRANCH == "master"
+    - if: $CI_COMMIT_BRANCH == "master" # or main
 ```
 
 ### `package.json` configuration

package/docs/recipes/release-workflow/distribution-channels.md

@@ -4,12 +4,12 @@ This recipe will walk you through a simple example that uses distribution channe
 
 This example uses the **semantic-release** default configuration:
 
-- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
+- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
 - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
 
 ## Initial release
 
-We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit` to `master`. When pushing that commit, **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.
+We'll start by making the first commit of the project, with the code for the initial release and the message `feat: initial commit` to `master` or `main`. When pushing that commit, **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.
 
 The Git history of the repository is:
 
@@ -19,7 +19,7 @@ The Git history of the repository is:
 
 ## Releasing a bug fix
 
-We can now continue to commit changes and release updates to our users. For example we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
+We can now continue to commit changes and release updates to our users. For example we can commit a bug fix with the message `fix: a fix` to `master` or `main`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
 
 The Git history of the repository is now:
 
@@ -63,7 +63,7 @@ We now want to develop a smaller, non-breaking feature. Its scope is small enoug
 
 If we were to commit that feature on `next` only a subset of users would get it, and we would need to wait for the end of our feedback period in order to make both the big and the small feature available to all users.
 
-Instead, we develop that small feature commit it to `master` with the message `feat: a small feature`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@latest` so all users can benefit from it right away.
+Instead, we develop that small feature commit it to `master` or `main` with the message `feat: a small feature`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@latest` so all users can benefit from it right away.
 
 The Git history of the repository is now:
 
@@ -78,7 +78,7 @@ The Git history of the repository is now:
 
 ## Porting a feature to next
 
-Most of our users now have access to the small feature, but we still need to make it available to our users using the `@next` dist-tag. To do so we need to merge our changes made on `master` (the commit `feat: a small feature`) into `next`. As `master` and `next` branches have diverged, this merge might require to resolve conflicts.
+Most of our users now have access to the small feature, but we still need to make it available to our users using the `@next` dist-tag. To do so we need to merge our changes made on `master` or `main` (the commit `feat: a small feature`) into `next`. As `master`/`main` and `next` branches have diverged, this merge might require to resolve conflicts.
 
 Once the conflicts are resolved and the merge commit is pushed to `next`, **semantic-release** will release the version `2.1.0` on the dist-tag `@next` which contains both our small and big feature.
 
@@ -91,14 +91,14 @@ The Git history of the repository is now:
 |  * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
 |  * fix: fix something on the big feature # => v2.0.1 on @next
 *  | feat: a small feature # => v1.1.0 on @latest
-|  * Merge branch master into next # => v2.1.0 on @next
+|  * Merge branch master/main into next # => v2.1.0 on @next
 ```
 
 ## Adding a version to latest
 
-After a period of feedback from our users using the `@next` dist-tag we feel confident to make our big feature available to all users. To do so we merge the `next` branch into `master`. There should be no conflict as `next` is strictly ahead of `master`.
+After a period of feedback from our users using the `@next` dist-tag we feel confident to make our big feature available to all users. To do so we merge the `next` branch into `master`/`main`. There should be no conflict as `next` is strictly ahead of `master`/`main`.
 
-Once the merge commit is pushed to `master`, **semantic-release** will add the version `2.1.0` to the dist-tag `@latest` so all users will receive it when installing out module with `npm install example-module`.
+Once the merge commit is pushed to `master`/`main`, **semantic-release** will add the version `2.1.0` to the dist-tag `@latest` so all users will receive it when installing out module with `npm install example-module`.
 
 The Git history of the repository is now:
 
@@ -109,9 +109,9 @@ The Git history of the repository is now:
 |  * feat: a big feature \n\n BREAKING CHANGE: it breaks something # => v2.0.0 on @next
 |  * fix: fix something on the big feature # => v2.0.1 on @next
 *  | feat: a small feature # => v1.1.0 on @latest
-|  * Merge branch master into next # => v2.1.0 on @next
+|  * Merge branch master/main into next # => v2.1.0 on @next
 | /|
-*  | Merge branch next into master # => v2.1.0 on @latest
+*  | Merge branch next into master/main # => v2.1.0 on @latest
 ```
 
-We can now continue to push new fixes and features on `master`, or a new breaking change on `next` as we did before.
+We can now continue to push new fixes and features on `master`/`main`, or a new breaking change on `next` as we did before.

package/docs/recipes/release-workflow/maintenance-releases.md

@@ -4,12 +4,12 @@ This recipe will walk you through a simple example that uses Git branches and di
 
 This example uses the **semantic-release** default configuration:
 
-- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
+- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
 - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
 
 ## Initial release
 
-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` **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.
+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.
 
 The Git history of the repository is:
 
@@ -21,7 +21,7 @@ The Git history of the repository is:
 
 We now decide to drop Node.js 6 support for our package, and require Node.js 8 or higher, which is a breaking change.
 
-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`.
+We commit that change with the message `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required` to `master`/`main`. When pushing that commit, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
 
 The Git history of the repository is now:
 
@@ -34,7 +34,7 @@ The Git history of the repository is now:
 
 One of our users request a new feature, however they cannot migrate to Node.js 8 or higher due to corporate policies.
 
-If we were to push that feature on `master` and release it, the new version would require Node.js 8 or higher as the release would also contain the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
+If we were to push that feature on `master`/`main` and release it, the new version would require Node.js 8 or higher as the release would also contain the commit `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
 
 Instead, we create the branch `1.x` from the tag `v1.0.0` with the command `git checkout -b 1.x v1.0.0` and we commit that feature with the message `feat: a feature` to the branch `1.x`. When pushing that commit, **semantic-release** will release the version `1.1.0` on the dist-tag `@release-1.x` so users who can't migrate to Node.js 8 or higher can benefit from it.
 
@@ -85,13 +85,13 @@ The Git history of the repository is now:
 |  *  | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
 ```
 
-## Porting bug fixes and features to master
+## Porting bug fixes and features to master/main
 
 Finally we want to make both our feature and bug fix available to users using the `@latest` dist-tag.
 
-To do so we need to merge the changes made on `1.x` (the commits `feat: a feature` and `fix: a fix`) into `master`. As `1.x` and `master` branches have diverged, this merge might require to resolve conflicts.
+To do so we need to merge the changes made on `1.x` (the commits `feat: a feature` and `fix: a fix`) into `master`/`main`. As `1.x` and `master`/`main` branches have diverged, this merge might require to resolve conflicts.
 
-Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.1.0` on the dist-tag `@latest` which now contains the breaking change feature, the feature and the bug fix.
+Once the conflicts are resolved and the merge commit is pushed to `master` or `main`, **semantic-release** will release the version `2.1.0` on the dist-tag `@latest` which now contains the breaking change feature, the feature and the bug fix.
 
 The Git history of the repository is now:
 
@@ -105,14 +105,14 @@ The Git history of the repository is now:
 |  | /|
 |  *  | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
 | /|  |
-*  |  | Merge branch 1.x into master # => v2.1.0 on @latest
+*  |  | Merge branch 1.x into master/main # => v2.1.0 on @latest
 ```
 
 ## Releasing a bug fix for version 2.1.0 users
 
 One of our users using the version `2.1.0` version reports a bug.
 
-We can simply commit the bug fix with the message `fix: another fix` to `master`. When pushing that commit, **semantic-release** will release the version `2.1.1` on the dist-tag `@latest`.
+We can simply commit the bug fix with the message `fix: another fix` to `master`/`main`. When pushing that commit, **semantic-release** will release the version `2.1.1` on the dist-tag `@latest`.
 
 The Git history of the repository is now:
 
@@ -126,15 +126,15 @@ The Git history of the repository is now:
 |  | /|
 |  *  | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
 | /|  |
-*  |  | Merge branch 1.x into master # => v2.1.0 on @latest
+*  |  | Merge branch 1.x into master/main # => v2.1.0 on @latest
 *  |  | fix: another fix # => v2.1.1 on @latest
 ```
 
-## Porting a bug fix from master to 1.x
+## Porting a bug fix from master/main to 1.x
 
 The bug fix `fix: another fix` also affects version `1.1.1` users, so we want to port it to the `1.x` branch.
 
-To do so we need to cherry pick our fix commit made on `master` (`fix: another fix`) into `1.x` with `git checkout 1.x && git cherry-pick <sha of fix: another fix>`. As `master` and `1.x` branches have diverged, the cherry picking might require to resolve conflicts.
+To do so we need to cherry pick our fix commit made on `master`/`main` (`fix: another fix`) into `1.x` with `git checkout 1.x && git cherry-pick <sha of fix: another fix>`. As `master`/`main` and `1.x` branches have diverged, the cherry picking might require to resolve conflicts.
 
 Once the conflicts are resolved and the commit is pushed to `1.x`, **semantic-release** will release the version `1.1.2` on the dist-tag `@release-1.x` which contains `feat: a feature`, `fix: a fix` and `fix: another fix` but not `feat: drop Node.js 6 support \n\n BREAKING CHANGE: Node.js >= 8 required`.
 
@@ -150,7 +150,7 @@ The Git history of the repository is now:
 |  | /|
 |  *  | Merge branch 1.0.x into 1.x # => v1.1.1 on @1.x
 | /|  |
-*  |  | Merge branch 1.x into master # => v2.1.0 on @latest
+*  |  | Merge branch 1.x into master/main # => v2.1.0 on @latest
 *  |  | fix: another fix # => v2.1.1 on @latest
 |  |  |
 |  *  | fix: another fix # => v1.1.2 on @1.x

package/docs/recipes/release-workflow/pre-releases.md

@@ -4,12 +4,12 @@ This recipe will walk you through a simple example that uses pre-releases to pub
 
 This example uses the **semantic-release** default configuration:
 
-- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
+- [branches](../../usage/configuration.md#branches): `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`
 - [plugins](../../usage/configuration.md#plugins): `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`
 
 ## Initial release
 
-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` **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.
+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.
 
 The Git history of the repository is:
 
@@ -46,7 +46,7 @@ With another feature, the Git history of the repository is now:
 
 In the meantime we can also continue to commit changes and release updates to our users.
 
-For example, we can commit a bug fix with the message `fix: a fix` to `master`. When pushing that commit, **semantic-release** will release the version `1.0.1` on the dist-tag `@latest`.
+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`.
 
 The Git history of the repository is now:
 
@@ -95,9 +95,9 @@ With another feature, the Git history of the repository is now:
 
 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.
 
-To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
+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.
 
-Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `2.0.0` on the dist-tag `@latest`.
+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`.
 
 The Git history of the repository is now:
 
@@ -111,14 +111,14 @@ The Git history of the repository is now:
 |  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
 |  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
 | /|  |
-*  |  | Merge branch beta into master # => v2.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
 ```
 
 ## Publishing the 3.0.0 alpha release to the beta distribution channel
 
 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.
 
-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`.
+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`.
 
 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.
 
@@ -134,7 +134,7 @@ The Git history of the repository is now:
 |  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
 |  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
 | /|  |
-*  |  | Merge branch beta into master # => v2.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
 |  | /|
 |  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
 ```
@@ -143,9 +143,9 @@ The Git history of the repository is now:
 
 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.
 
-To do so we need to merge our changes made on `beta` into `master`. As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
+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.
 
-Once the conflicts are resolved and the merge commit is pushed to `master`, **semantic-release** will release the version `3.0.0` on the dist-tag `@latest`.
+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`.
 
 The Git history of the repository is now:
 
@@ -159,18 +159,18 @@ The Git history of the repository is now:
 |  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
 |  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
 | /|  |
-*  |  | Merge branch beta into master # => v2.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
 |  | /|
 |  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
 | /|  |
-*  |  | Merge branch beta into master # => v3.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v3.0.0 on @latest
 ```
 
 ## Working on a third future release
 
 We can now start to work on a new future major release, version `4.0.0`, on the `@beta` distribution channel.
 
-To do so we first need to update the `beta` branch with all the changes from `master` (the commits `fix: a fix`). As `beta` and `master` branches have diverged, this merge might require to resolve conflicts.
+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.
 
 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`.
 
@@ -186,12 +186,12 @@ The Git history of the repository is now:
 |  |  * feat: first feature of other release \n\n BREAKING CHANGE: it breaks something # => v3.0.0-alpha.1 on @alpha
 |  |  * feat: second feature of other release # => v3.0.0-alpha.2 on @alpha
 | /|  |
-*  |  | Merge branch beta into master # => v2.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v2.0.0 on @latest
 |  | /|
 |  *  | Merge branch alpha into beta # => v3.0.0-beta.1 on @beta
 | /|  |
-*  |  | Merge branch beta into master # => v3.0.0 on @latest
+*  |  | Merge branch beta into master/main # => v3.0.0 on @latest
 | \|  |
-|  *  | Merge branch master into beta
+|  *  | Merge branch master/main into beta
 |  *  | feat: new feature # => v3.1.0-beta.1 on @beta
 ```

package/docs/support/FAQ.md

@@ -2,13 +2,52 @@
 
 ## Why is the `package.json`’s version not updated in my repository?
 
-[`@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).
+### It is not needed for semantic-release to do its job
 
-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
+[`@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.
+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.
+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.
 
-However, the [`@semantic-release/git`](https://github.com/semantic-release/git) plugin can be used to push the updated `package.json` as well as other files to the Git repository.
+### It can lead to confusion
 
-If you wish to only update the `package.json` and push via Git you can set the project to `"private": true,` within your `package.json` to prevent publishing to [the npm registry](https://www.npmjs.com).
+Some teams find value in being able to reference the repository to determine the current latest version available for the published package.
+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.
+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.
+The [npm CLI](https://docs.npmjs.com/cli/npm) can be used to consult the registry with the following command:
+
+```shell
+npm dist-tags ls <package-name>
+```
+
+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`.
+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`.
+
+### Making commits during the release process adds significant complexity
+
+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.
+
+Making commits and pushing them back to the repository adds significant additional complexity to your release process that can be avoided:
+
+- 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.
+- 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.
+  (We recommend disabling tools like this for automated commits, but you need to decide what is appropriate for your project)
+
+### There are valid reasons to commit during a release
+
+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.
+In such a case you will want to use [`@semantic-release/git`](https://github.com/semantic-release/git) to coordinate the commit and push.
+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).
+
+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.
+
+## Should release notes be committed to a `CHANGELOG.md` in my repository during a release?
+
+[`@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.
+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.
+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).
+
+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.
+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.
 
 ## How can I use a npm build script that requires the `package.json`’s version ?
 
@@ -183,11 +222,11 @@ This is fully customizable with the [`@semantic-release/commit-analyzer`](https:
 
 ## Is it _really_ a good idea to release on every push?
 
-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` you might not treat your `master` branch as intended.
+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.
 
 From [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/index.html):
 
-> 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 branch is always deployable.
+> 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.
 
 If you need more control over the timing of releases, see [Triggering a release](../../README.md#triggering-a-release) for different options.
 

package/docs/support/troubleshooting.md

@@ -66,5 +66,5 @@ To recover from that situation, do the following:
 
 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`.
 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`
-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"]}'`
+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"]}'`
 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/configuration.md

@@ -20,7 +20,7 @@ Additionally, metadata of Git tags generated by **semantic-release** can be cust
 
 Alternatively, some options can be set via CLI arguments.
 
-The following three examples are the same.
+The following three examples are the same. Use main instead of master if your default branch is main.
 
 - Via `release` key in the project's `package.json` file:
 
@@ -77,19 +77,21 @@ List of modules or file paths containing a [shareable configuration](shareable-c
 ### branches
 
 Type: `Array`, `String`, `Object`<br>
-Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`<br>
+Default: `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'main', 'next', 'next-major', {name: 'beta', prerelease: true}, {name: 'alpha', prerelease: true}]`<br>
 CLI arguments: `--branches`
 
 The branches on which releases should happen. By default **semantic-release** will release:
 
-- regular releases to the default distribution channel from the branch `master`
+- regular releases to the default distribution channel from the branch `master` or `main`
 - regular releases to a distribution channel matching the branch name from any existing branch with a name matching a maintenance release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a number)
 - regular releases to the `next` distribution channel from the branch `next` if it exists
 - regular releases to the `next-major` distribution channel from the branch `next-major` if it exists
 - pre-releases to the `beta` distribution channel from the branch `beta` if it exists
 - pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists
 
-**Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` branch.
+**Note**: Branches configuration key accepts [**micromatch**](https://github.com/micromatch/micromatch?tab=readme-ov-file#matching-features) globs.
+
+**Note**: If your repository does not have a release branch, then **semantic-release** will fail with an `ERELEASEBRANCHES` error message. If you are using the default configuration, you can fix this error by pushing a `master` or `main` branch.
 
 **Note**: Once **semantic-release** is configured, any user with the permission to push commits on one of those branches will be able to publish a release. It is recommended to protect those branches, for example with [GitHub protected branches](https://docs.github.com/github/administering-a-repository/about-protected-branches).
 
@@ -173,7 +175,7 @@ If a release has been published before setting up **semantic-release** you must
 
 If the previous releases were published with [`npm publish`](https://docs.npmjs.com/cli/publish) this should already be the case.
 
-For example, if your release branch is `master`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `master` history and is tagged with `v1.1.0`.
+For example, if your release branch is `master`/`main`, the last release published on your project is `1.1.0` and the last commit included has the sha `1234567`, you must make sure this commit is in `master`/`main` history and is tagged with `v1.1.0`.
 
 ```bash
 # Make sure the commit 1234567 is in the release branch history

package/docs/usage/workflow-configuration.md

@@ -1,11 +1,12 @@
-# Workflow configuration
+# Release Workflow configuration
 
-**semantic-release** allow to manage and automate complex release workflow, based on multiple Git branches and distribution channels. This allow to:
+**semantic-release** enables managing and automating complex release workflow, based on multiple Git branches and distribution channels.
+This enables:
 
-- Distribute certain releases to a particular group of users via distribution channels
-- Manage the availability of releases on distribution channels via branches merge
-- Maintain multiple lines of releases in parallel
-- Work on large future releases outside the normal flow of one version increment per Git push
+- Distributing certain releases to a particular group of users via distribution channels
+- Managing the availability of releases on distribution channels via branches merge
+- Maintaining multiple lines of releases in parallel
+- Working on large future releases outside the normal flow of one version increment per Git push
 
 See [Release workflow recipes](../recipes/release-workflow/README.md#release-workflow) for detailed examples.
 

package/index.d.ts

@@ -445,7 +445,7 @@ declare module "semantic-release" {
      * **semantic-release** will release:
      *
      *  * regular releases to the default distribution channel from the
-     *    branch `master`
+     *    branch `master` / `main`
      *  * regular releases to a distribution channel matching the branch
      *    name from any existing branch with a name matching a maintenance
      *    release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a
@@ -462,7 +462,7 @@ declare module "semantic-release" {
      * **Note**: If your repository does not have a release branch, then
      * **semantic-release** will fail with an `ERELEASEBRANCHES` error
      * message. If you are using the default configuration, you can fix
-     * this error by pushing a `master` branch.
+     * this error by pushing a `master`/`main branch.
      *
      * **Note**: Once **semantic-release** is configured, any user with the
      * permission to push commits on one of those branches will be able to
@@ -587,7 +587,7 @@ declare module "semantic-release" {
      * **semantic-release** will release:
      *
      *  * regular releases to the default distribution channel from the
-     *    branch `master`
+     *    branch `master`/`main
      *  * regular releases to a distribution channel matching the branch
      *    name from any existing branch with a name matching a maintenance
      *    release range (`N.N.x` or `N.x.x` or `N.x` with `N` being a
@@ -604,7 +604,7 @@ declare module "semantic-release" {
      * **Note**: If your repository does not have a release branch, then
      * **semantic-release** will fail with an `ERELEASEBRANCHES` error
      * message. If you are using the default configuration, you can fix
-     * this error by pushing a `master` branch.
+     * this error by pushing a `master`/`main` branch.
      *
      * **Note**: Once **semantic-release** is configured, any user with the
      * permission to push commits on one of those branches will be able to

package/lib/definitions/errors.js

@@ -240,7 +240,7 @@ export function ERELEASEBRANCHES({ branches }) {
       "docs/usage/configuration.md#branches"
     )}).
 
-This may occur if your repository does not have a release branch, such as \`master\`.
+This may occur if your repository does not have a release branch, such as \`master\` or \`main\`.
 
 Your configuration for the problematic branches is \`${stringify(branches)}\`.`,
   };

package/lib/get-config.js

@@ -64,6 +64,7 @@ export default async (context, cliOptions) => {
     branches: [
       "+([0-9])?(.{+([0-9]),x}).x",
       "master",
+      "main",
       "next",
       "next-major",
       { name: "beta", prerelease: true },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "semantic-release",
   "description": "Automated semver compliant package publishing",
-  "version": "23.0.8",
+  "version": "23.1.0",
   "type": "module",
   "author": "Stephan Bönnemann <stephan@boennemann.me> (http://boennemann.me)",
   "ava": {
@@ -58,7 +58,7 @@
     "yargs": "^17.5.1"
   },
   "devDependencies": {
-    "ava": "6.1.2",
+    "ava": "6.1.3",
     "c8": "9.1.0",
     "clear-module": "4.1.2",
     "codecov": "3.8.3",
@@ -76,7 +76,7 @@
     "p-retry": "6.2.0",
     "prettier": "3.2.5",
     "publint": "0.2.7",
-    "sinon": "17.0.1",
+    "sinon": "17.0.2",
     "stream-buffers": "3.0.2",
     "tempy": "3.1.0",
     "testdouble": "3.20.2"
@@ -162,5 +162,5 @@
       "github>semantic-release/.github:renovate-config"
     ]
   },
-  "packageManager": "npm@10.5.1"
+  "packageManager": "npm@10.7.0"
 }