From a1fa3c0016f38ecc502d10f64466a0c7fadac5cb Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 24 Apr 2026 23:39:53 +0100 Subject: [PATCH 01/25] refactor(running): simplify file extension --- src/content/docs/usage/{running.mdx => running.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/content/docs/usage/{running.mdx => running.md} (100%) diff --git a/src/content/docs/usage/running.mdx b/src/content/docs/usage/running.md similarity index 100% rename from src/content/docs/usage/running.mdx rename to src/content/docs/usage/running.md From 31ed6286886432e2999ee0a332400451f0615f9f Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 24 Apr 2026 23:58:00 +0100 Subject: [PATCH 02/25] feat(docs): move plugins, shareable configurations, and workflow configuration to new foundation docs --- src/content/docs/{usage => foundation}/plugins.md | 0 .../docs/{usage => foundation}/shareable-configurations.md | 0 src/content/docs/{usage => foundation}/workflow-configuration.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename src/content/docs/{usage => foundation}/plugins.md (100%) rename src/content/docs/{usage => foundation}/shareable-configurations.md (100%) rename src/content/docs/{usage => foundation}/workflow-configuration.md (100%) diff --git a/src/content/docs/usage/plugins.md b/src/content/docs/foundation/plugins.md similarity index 100% rename from src/content/docs/usage/plugins.md rename to src/content/docs/foundation/plugins.md diff --git a/src/content/docs/usage/shareable-configurations.md b/src/content/docs/foundation/shareable-configurations.md similarity index 100% rename from src/content/docs/usage/shareable-configurations.md rename to src/content/docs/foundation/shareable-configurations.md diff --git a/src/content/docs/usage/workflow-configuration.md b/src/content/docs/foundation/workflow-configuration.md similarity index 100% rename from src/content/docs/usage/workflow-configuration.md rename to src/content/docs/foundation/workflow-configuration.md From ca742e6155db2b4756f55d2bd63a0b4a6d58f897 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 25 Apr 2026 01:35:01 +0100 Subject: [PATCH 03/25] feat(docs): reorganize navigation structure to include foundation section --- astro.config.js | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/astro.config.js b/astro.config.js index f3a68ac..1920919 100644 --- a/astro.config.js +++ b/astro.config.js @@ -50,9 +50,19 @@ export default defineConfig({ { slug: "usage/configuration" }, { slug: "usage/ci-configuration" }, { slug: "usage/running" }, - { slug: "usage/plugins" }, - { slug: "usage/workflow-configuration" }, - { slug: "usage/shareable-configurations" }, + ], + }, + { + label: "Foundations", + items: [ + { slug: "foundation" }, + { slug: "foundation/how-it-works" }, + { slug: "foundation/steps" }, + { slug: "foundation/considerations" }, + { slug: "foundation/supported-branching" }, + { slug: "foundation/workflow-configuration" }, + { slug: "foundation/plugins" }, + { slug: "foundation/shareable-configurations" }, ], }, { From da88597457a8dbb7a4776534609edb5b00b2bdd6 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 25 Apr 2026 01:39:37 +0100 Subject: [PATCH 04/25] feat(docs): add foundational concepts and navigation links to new index page --- src/content/docs/foundation/index.mdx | 51 +++++++++++++++++++++++++++ src/styles/global.css | 1 + 2 files changed, 52 insertions(+) create mode 100644 src/content/docs/foundation/index.mdx diff --git a/src/content/docs/foundation/index.mdx b/src/content/docs/foundation/index.mdx new file mode 100644 index 0000000..116bd97 --- /dev/null +++ b/src/content/docs/foundation/index.mdx @@ -0,0 +1,51 @@ +--- +title: Foundations +--- + +import { CardGrid, LinkCard } from "@astrojs/starlight/components"; + +Learn the concepts, constraints, and mental models that make **semantic-release** work. + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/src/styles/global.css b/src/styles/global.css index 9086cbc..f550209 100644 --- a/src/styles/global.css +++ b/src/styles/global.css @@ -60,6 +60,7 @@ article.card, .dialog-frame, .pagefind-ui__search-input, dialog-frame, +.sl-link-card, .page-context-action__compact-copy-btn, .page-context-action__compact-scroll-top-btn, .page-context-action__compact-kebab-btn, From c1c57b9f1e601e7bf57782caeb30969947986fae Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 25 Apr 2026 02:44:30 +0100 Subject: [PATCH 05/25] feat(docs): add considerations and supported branching models documentation from https://github.com/semantic-release/semantic-release/pull/3264 Co-authored-by: travi <126441+travi@users.noreply.github.com> --- src/content/docs/foundation/considerations.md | 39 ++++++++++++ .../docs/foundation/supported-branching.md | 62 +++++++++++++++++++ 2 files changed, 101 insertions(+) create mode 100644 src/content/docs/foundation/considerations.md create mode 100644 src/content/docs/foundation/supported-branching.md diff --git a/src/content/docs/foundation/considerations.md b/src/content/docs/foundation/considerations.md new file mode 100644 index 0000000..03f2945 --- /dev/null +++ b/src/content/docs/foundation/considerations.md @@ -0,0 +1,39 @@ +--- +title: Considerations +--- +**semantic-release** is + +- an opinionated release tool +- a tool to simplify versioning releases semantically first, automating steps related to a release process second +- a tool that encourages engineering practices that support delivering high quality at a sustainable pace (continuous deployment/release, trunk based deployment) + +## Are you interested in **semantic-release** because of our primary or secondary goals + +If your primary attraction is for automatic release note generation rather than semantic versioning, you may want to reconsider if **semantic-release** is the right fit for your goals. + +## Do you actually need semantic versioning? + +The use of the word "semantic" in the term "semantic versioning" has the intent that the structure of the version conveys specific meaning. +Consult https://semver.org/ for details about the details of the specific meaning, but keep in mind that the semantics are from the perspective of a consumer. + +Semantic versioning is most useful for software releases that are consumed programmatically. +Common examples are libraries/packages consumed as dependencies. +Base Docker images can also fall in this category because they are consumed in a way that other layers build on top of them. + +Applications that are deployed directly to a runtime environment lack an audience to benefit from the benefits of semantic versioning. +Docker images that are published to a registry only for the purpose of deploying directly to a runtime environment fall into this category, even though they are a published asset. +Often, using the git SHA as the version for such assets is a better choice than versioning them semantically. + +## Can you simplify the release steps automated by **semantic-release**? + +Updating the version in the `package.json` of an npm package or providing release notes in a `CHANGELOG.md` file are popular release steps +that can be enabled with **semantic-release** using the [changelog](https://github.com/semantic-release/changelog) and [git](https://github.com/semantic-release/git) plugins. +However, those two plugins are intentionally _not_ included in the default configuration of **semantic-release** because +[they are not necessary for **semantic-release** to function](https://semantic-release.gitbook.io/semantic-release/support/faq#it-is-not-needed-for-semantic-release-to-do-its-job) +and [making commits during the release process adds significant complexity](https://semantic-release.gitbook.io/semantic-release/support/faq#making-commits-during-the-release-process-adds-significant-complexity). + +Please consider the trade-offs of adding those plugins to your release configuration for potentially unnecessary goals. + +## Is the branching strategy of your project supported by **semantic-release**? + +[supported branching strategies](./supported-branching.md) \ No newline at end of file diff --git a/src/content/docs/foundation/supported-branching.md b/src/content/docs/foundation/supported-branching.md new file mode 100644 index 0000000..08eeb83 --- /dev/null +++ b/src/content/docs/foundation/supported-branching.md @@ -0,0 +1,62 @@ +--- +title: Supported Branching Models +--- +## Trunk Based Development + +- https://trunkbaseddevelopment.com/ +- https://minimumcd.org/minimumcd/tbd/ + +### Committing Straight to the Trunk + +- https://trunkbaseddevelopment.com/#trunk-based-development-for-smaller-teams +- https://trunkbaseddevelopment.com/committing-straight-to-the-trunk/ + +### Short-Lived Feature Branches + +- https://trunkbaseddevelopment.com/#scaled-trunk-based-development +- https://trunkbaseddevelopment.com/short-lived-feature-branches/ + +### Continuous Integration + +- https://minimumcd.org/minimumcd/ci/ + +### Continuous Deployment/Release + +- https://trunkbaseddevelopment.com/continuous-delivery/#continuous-deployment + +## GitHub Flow + +- https://githubflow.github.io/ +- https://docs.github.com/en/get-started/using-github/github-flow + +## Officially Unsupported Branching Models + +### Trunk Based Development: Branch for release + +https://trunkbaseddevelopment.com/branch-for-release/ + +exception: + +- https://trunkbaseddevelopment.com/branch-for-release/#late-creation-of-release-branches + - our maintenance release is an example of this approach + +### git-flow + +- https://nvie.com/posts/a-successful-git-branching-model/ +- https://jeffkreeftmeijer.com/git-flow/ + +Even if this is strategy that you find useful for the applications you are building, which [the original author of the git-flow branching model recommends against](https://nvie.com/posts/a-successful-git-branching-model/), +we do not recommend this branching model when releasing artifacts with **semantic-release**. +While the [same reflection](https://nvie.com/posts/a-successful-git-branching-model/) that recommends against using git-flow for web apps suggests that it may still be a good fit for explicitly versioned software, +**semantic-release** is built with Continuous Deployment/Release in mind instead. + +While some have found that the [Pre-release workflow](./workflow-configuration.md#pre-release-branches) enabled by **semantic-release** can be used to _simulate_ a git-flow-like workflow, +it is also worth noting that workflow is not intended for such a use case and requests for support when attempting to use it that way will be closed by our team. + +### Workflows that Release for Testing Before Promotion to a Stable Release + +- https://trunkbaseddevelopment.com/styles/#the-importance-of-a-local-build + +### Monorepos + +While not specifically a branching strategy, \ No newline at end of file From a437c0876559c3d42f7008c23b8e199ea45386c9 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 25 Apr 2026 12:31:34 +0100 Subject: [PATCH 06/25] feat(docs): add "How it Works" documentation for semantic-release Co-authored-by: Copilot --- src/content/docs/foundation/how-it-works.md | 61 +++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 src/content/docs/foundation/how-it-works.md diff --git a/src/content/docs/foundation/how-it-works.md b/src/content/docs/foundation/how-it-works.md new file mode 100644 index 0000000..9f6c4df --- /dev/null +++ b/src/content/docs/foundation/how-it-works.md @@ -0,0 +1,61 @@ +--- +title: How it Works +--- + +**semantic-release** automates package release workflows by turning commit history into predictable versioning and publishing decisions. + +At a high level, it answers three questions on every run: + +1. Should a release happen? +2. If yes, what version should be released? +3. Where and how should that release be published? + +## The core model + +When `semantic-release` runs in CI on a configured release branch, it compares commits since the last Git tag and determines release impact from commit semantics. + +This relies on a formalized commit message convention. By default, **semantic-release** uses the [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md), where the type prefix in each commit message signals the impact of that change: + +- `fix` commits produce patch releases +- `feat` commits produce minor releases +- `BREAKING CHANGE` in a commit footer produces major releases + +If no commits since the last release carry a recognized type, no release is published. + +Tools like [commitizen](https://github.com/commitizen/cz-cli) and [commitlint](https://github.com/conventional-changelog/commitlint) can help contributors author valid commit messages consistently. + +For deeper details on commit analysis and lifecycle phases, see [Release Steps](/foundation/steps/) and [Plugins](/foundation/plugins/). + +## Why CI is central + +The release command is designed to run in CI after successful builds. This keeps releases deterministic and removes manual, error-prone release actions. + +Each push or merge to a release branch can trigger a release run. Whether that run publishes depends on commit analysis, branch configuration, and plugin behavior. + +For setup guidance, see [CI Configuration](/usage/ci-configuration/) and [Getting Started](/usage/getting-started/). + +## What drives release behavior + +Release behavior is determined by a small set of inputs: + +- Commit history since the last release tag +- Branch configuration (release, maintenance, pre-release) +- Plugin pipeline and plugin options +- Credentials available in the CI environment + +Those inputs produce outputs such as: + +- The next semantic version +- Release notes +- Git tags +- Published artifacts or channels (for example npm dist-tags) + +See [Release Workflow Configuration](/foundation/workflow-configuration/) and [Supported Branching Models](/foundation/supported-branching/) for branching behavior. + +## Safety and constraints + +**semantic-release** is intentionally opinionated. It prioritizes consistent semantic versioning and continuous delivery/release workflows over manual or ad hoc processes. + +That means it may refuse to publish when conditions are invalid, such as version conflicts across branches, missing release branches, or failed verification steps. + +Read [Considerations](/foundation/considerations/) before designing a workflow that diverges from these assumptions. \ No newline at end of file From 592966018b526820f26ded2e238549b1cdc3f9a5 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sun, 26 Apr 2026 16:56:26 +0100 Subject: [PATCH 07/25] feat(docs): add release steps documentation for semantic-release lifecycle --- src/content/docs/foundation/steps.md | 64 ++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 src/content/docs/foundation/steps.md diff --git a/src/content/docs/foundation/steps.md b/src/content/docs/foundation/steps.md new file mode 100644 index 0000000..94f536d --- /dev/null +++ b/src/content/docs/foundation/steps.md @@ -0,0 +1,64 @@ +--- +title: Release Steps +--- + +This page explains the release lifecycle that runs when `semantic-release` is executed. If you are new to the overall model, read [How it Works](/foundation/how-it-works/) first. + +## Lifecycle overview + +After tests pass and `semantic-release` starts, it evaluates the repository state and executes release steps in a fixed order. + +| Step | Purpose | +| --- | --- | +| Verify Conditions | Confirm required configuration and credentials are available. | +| Get Last Release | Find the most recent release by reading Git tags/history. | +| Analyze Commits | Determine whether to release and which version type to produce. | +| Verify Release | Validate the computed release metadata before publishing. | +| Generate Notes | Build release notes for the commits included in this release. | +| Create Git Tag | Tag the release version in Git. | +| Prepare | Perform pre-publish updates such as assets or files. | +| Publish | Publish artifacts to configured destinations and channels. | +| Notify | Report success or failure through provider integrations. | + +The order is important. A failure in an early step prevents later steps from running. + +## How steps are implemented + +Each lifecycle step is implemented by plugins. Some steps are optional, some are required for a valid release pipeline. + +- `analyzeCommits` is required to decide version impact +- Most other steps depend on which plugins you configure +- If multiple plugins implement the same step, they execute in plugin order + +For plugin responsibilities and execution details, see [Plugins](/foundation/plugins/). + +## Release decision logic + +The `analyzeCommits` step is the decision point for whether a release is created. + +- No relevant commits since the last release means no new release +- `fix` commits typically result in a patch release +- `feat` commits typically result in a minor release +- `BREAKING CHANGE` results in a major release + +Commit parsing depends on your configured commit analyzer and presets. See [How it Works](/foundation/how-it-works/) for the conceptual model and [Configuration](/usage/configuration/) for setup details. + +## Branch and channel impact + +The same steps run regardless of branch type, but release outcomes vary with branch strategy and channel configuration. + +- Release branches publish regular versions +- Maintenance branches publish within defined ranges +- Pre-release branches publish pre-release identifiers + +See [Supported Branching Models](/foundation/supported-branching/) and [Release Workflow Configuration](/foundation/workflow-configuration/) for branch behavior and constraints. + +## Operational expectations + +To keep releases deterministic, run `semantic-release` only in CI and only after all required checks pass. + +For implementation guidance, see: + +- [Getting Started](/usage/getting-started/) +- [CI Configuration](/usage/ci-configuration/) +- [Running semantic-release](/usage/running/) \ No newline at end of file From 9ff5319da973a73134f680b711cffcd022d49fcd Mon Sep 17 00:00:00 2001 From: babblebey Date: Sun, 26 Apr 2026 17:39:17 +0100 Subject: [PATCH 08/25] feat(docs): add label to foundation overview navigation item --- astro.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/astro.config.js b/astro.config.js index 1920919..b2a5688 100644 --- a/astro.config.js +++ b/astro.config.js @@ -55,7 +55,7 @@ export default defineConfig({ { label: "Foundations", items: [ - { slug: "foundation" }, + { slug: "foundation", label: "Overview" }, { slug: "foundation/how-it-works" }, { slug: "foundation/steps" }, { slug: "foundation/considerations" }, From 7de44a3c1bc38ff5d4bfbe7249eaac4cfb0e000b Mon Sep 17 00:00:00 2001 From: babblebey Date: Sun, 26 Apr 2026 18:29:41 +0100 Subject: [PATCH 09/25] feat(docs): improve formatting and consistency across foundation documentation --- astro.config.js | 4 +- src/content/docs/foundation/considerations.md | 3 +- src/content/docs/foundation/how-it-works.md | 2 +- src/content/docs/foundation/index.mdx | 60 +++++++++---------- src/content/docs/foundation/steps.md | 24 ++++---- .../docs/foundation/supported-branching.md | 3 +- src/content/docs/usage/ci-configuration.md | 25 ++++---- src/content/docs/usage/configuration.md | 8 ++- src/content/docs/usage/running.md | 5 +- 9 files changed, 72 insertions(+), 62 deletions(-) diff --git a/astro.config.js b/astro.config.js index b2a5688..1b43c8a 100644 --- a/astro.config.js +++ b/astro.config.js @@ -58,8 +58,8 @@ export default defineConfig({ { slug: "foundation", label: "Overview" }, { slug: "foundation/how-it-works" }, { slug: "foundation/steps" }, - { slug: "foundation/considerations" }, - { slug: "foundation/supported-branching" }, + { slug: "foundation/considerations" }, + { slug: "foundation/supported-branching" }, { slug: "foundation/workflow-configuration" }, { slug: "foundation/plugins" }, { slug: "foundation/shareable-configurations" }, diff --git a/src/content/docs/foundation/considerations.md b/src/content/docs/foundation/considerations.md index 03f2945..e63331b 100644 --- a/src/content/docs/foundation/considerations.md +++ b/src/content/docs/foundation/considerations.md @@ -1,6 +1,7 @@ --- title: Considerations --- + **semantic-release** is - an opinionated release tool @@ -36,4 +37,4 @@ Please consider the trade-offs of adding those plugins to your release configura ## Is the branching strategy of your project supported by **semantic-release**? -[supported branching strategies](./supported-branching.md) \ No newline at end of file +[supported branching strategies](./supported-branching.md) diff --git a/src/content/docs/foundation/how-it-works.md b/src/content/docs/foundation/how-it-works.md index 9f6c4df..fb2f803 100644 --- a/src/content/docs/foundation/how-it-works.md +++ b/src/content/docs/foundation/how-it-works.md @@ -58,4 +58,4 @@ See [Release Workflow Configuration](/foundation/workflow-configuration/) and [S That means it may refuse to publish when conditions are invalid, such as version conflicts across branches, missing release branches, or failed verification steps. -Read [Considerations](/foundation/considerations/) before designing a workflow that diverges from these assumptions. \ No newline at end of file +Read [Considerations](/foundation/considerations/) before designing a workflow that diverges from these assumptions. diff --git a/src/content/docs/foundation/index.mdx b/src/content/docs/foundation/index.mdx index 116bd97..42c81bf 100644 --- a/src/content/docs/foundation/index.mdx +++ b/src/content/docs/foundation/index.mdx @@ -13,39 +13,39 @@ Learn the concepts, constraints, and mental models that make **semantic-release* description="Start with the high-level release lifecycle and how the system fits together." /> - - - - - - - - - + + + + + + + + + - \ No newline at end of file + diff --git a/src/content/docs/foundation/steps.md b/src/content/docs/foundation/steps.md index 94f536d..a43f4c7 100644 --- a/src/content/docs/foundation/steps.md +++ b/src/content/docs/foundation/steps.md @@ -8,17 +8,17 @@ This page explains the release lifecycle that runs when `semantic-release` is ex After tests pass and `semantic-release` starts, it evaluates the repository state and executes release steps in a fixed order. -| Step | Purpose | -| --- | --- | -| Verify Conditions | Confirm required configuration and credentials are available. | -| Get Last Release | Find the most recent release by reading Git tags/history. | -| Analyze Commits | Determine whether to release and which version type to produce. | -| Verify Release | Validate the computed release metadata before publishing. | -| Generate Notes | Build release notes for the commits included in this release. | -| Create Git Tag | Tag the release version in Git. | -| Prepare | Perform pre-publish updates such as assets or files. | -| Publish | Publish artifacts to configured destinations and channels. | -| Notify | Report success or failure through provider integrations. | +| Step | Purpose | +| ----------------- | --------------------------------------------------------------- | +| Verify Conditions | Confirm required configuration and credentials are available. | +| Get Last Release | Find the most recent release by reading Git tags/history. | +| Analyze Commits | Determine whether to release and which version type to produce. | +| Verify Release | Validate the computed release metadata before publishing. | +| Generate Notes | Build release notes for the commits included in this release. | +| Create Git Tag | Tag the release version in Git. | +| Prepare | Perform pre-publish updates such as assets or files. | +| Publish | Publish artifacts to configured destinations and channels. | +| Notify | Report success or failure through provider integrations. | The order is important. A failure in an early step prevents later steps from running. @@ -61,4 +61,4 @@ For implementation guidance, see: - [Getting Started](/usage/getting-started/) - [CI Configuration](/usage/ci-configuration/) -- [Running semantic-release](/usage/running/) \ No newline at end of file +- [Running semantic-release](/usage/running/) diff --git a/src/content/docs/foundation/supported-branching.md b/src/content/docs/foundation/supported-branching.md index 08eeb83..202d569 100644 --- a/src/content/docs/foundation/supported-branching.md +++ b/src/content/docs/foundation/supported-branching.md @@ -1,6 +1,7 @@ --- title: Supported Branching Models --- + ## Trunk Based Development - https://trunkbaseddevelopment.com/ @@ -59,4 +60,4 @@ it is also worth noting that workflow is not intended for such a use case and re ### Monorepos -While not specifically a branching strategy, \ No newline at end of file +While not specifically a branching strategy, diff --git a/src/content/docs/usage/ci-configuration.md b/src/content/docs/usage/ci-configuration.md index c47bd33..4cf8c34 100644 --- a/src/content/docs/usage/ci-configuration.md +++ b/src/content/docs/usage/ci-configuration.md @@ -1,6 +1,7 @@ --- title: "CI Configuration" --- + Configure CI to run **semantic-release** by following two requirements: run it only after all tests pass, and configure the authentication needed to publish releases. ## Choose your CI Service @@ -21,7 +22,7 @@ For details about the CI environment variables that **semantic-release** detects ## Run `semantic-release` only after all tests succeeded -The `semantic-release` command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the `semantic-release` command is executed only after all jobs are successful. +The `semantic-release` command must be executed only after all the tests in the CI build pass. If the build runs multiple jobs (for example to test on multiple Operating Systems or Node versions) the CI has to be configured to guarantee that the `semantic-release` command is executed only after all jobs are successful. ## Authentication @@ -35,13 +36,13 @@ Prefer short-lived credentials over long-lived secrets when your platform suppor **semantic-release** requires push access to the project Git repository in order to create [Git tags](https://git-scm.com/book/en/v2/Git-Basics-Tagging). The Git authentication can be set with one of the following environment variables: -| Variable | Description | -| ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GH_TOKEN` or `GITHUB_TOKEN` | GitHub token for repository authentication. In GitHub Actions, the workflow-provided `GITHUB_TOKEN` is automatically available; prefer this or a GitHub App installation token when available; use a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) only when required. | -| `GL_TOKEN` or `GITLAB_TOKEN` | A GitLab [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/). | -| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). | -| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. | -| `GIT_CREDENTIALS` | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `:`. The username and password must each be individually URL encoded, not the `:` separating them. | +| Variable | Description | +| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GH_TOKEN` or `GITHUB_TOKEN` | GitHub token for repository authentication. In GitHub Actions, the workflow-provided `GITHUB_TOKEN` is automatically available; prefer this or a GitHub App installation token when available; use a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) only when required. | +| `GL_TOKEN` or `GITLAB_TOKEN` | A GitLab [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/). | +| `BB_TOKEN` or `BITBUCKET_TOKEN` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html). | +| `BB_TOKEN_BASIC_AUTH` or `BITBUCKET_TOKEN_BASIC_AUTH` | A Bitbucket [personal access token](https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html) with basic auth support. For clarification `user:token` has to be the value of this env. | +| `GIT_CREDENTIALS` | [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding) Git username and password in the format `:`. The username and password must each be individually URL encoded, not the `:` separating them. | Alternatively the Git authentication can be set up via [SSH keys](/recipes/git-hosted-services/git-auth-ssh-keys). @@ -51,10 +52,10 @@ For GitHub releases, see [@semantic-release/github authentication and permission Most **semantic-release** [plugins](/usage/plugins) require setting up authentication in order to publish to a package manager registry. The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) and [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugins require the following environment variables: -| Variable | Description | -| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `NPM_TOKEN` |

npm token for publishing to npm. Trusted publishing is the recommended approach when publishing to the official registry. A token is required when publishing to alternative registries. See CI configuration recipes for setup options.

| -| `GH_TOKEN` or `GITHUB_TOKEN` |

GitHub authentication token for publishing releases. See CI configuration recipes for setup options.

| +| Variable | Description | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `NPM_TOKEN` |

npm token for publishing to npm. Trusted publishing is the recommended approach when publishing to the official registry. A token is required when publishing to alternative registries. See CI configuration recipes for setup options.

| +| `GH_TOKEN` or `GITHUB_TOKEN` |

GitHub authentication token for publishing releases. See CI configuration recipes for setup options.

| See each plugin's documentation for the environment variables required. diff --git a/src/content/docs/usage/configuration.md b/src/content/docs/usage/configuration.md index c88103d..8bc13ec 100644 --- a/src/content/docs/usage/configuration.md +++ b/src/content/docs/usage/configuration.md @@ -1,6 +1,7 @@ --- title: "Configuration" --- + Configure semantic-release options, plugins, and release branches via config files, CLI arguments, or shareable configurations. **semantic-release** configuration consists of: @@ -24,6 +25,7 @@ Additionally, metadata of Git tags generated by **semantic-release** can be cust The following three examples are the same. Use `master` instead of `main` if your default branch is `master`. - Via `release` key in the project's `package.json` file: + ```json { "release": { @@ -33,6 +35,7 @@ The following three examples are the same. Use `master` instead of `main` if you ``` - Via `.releaserc` file: + ```json { "branches": ["main", "next"] @@ -40,6 +43,7 @@ The following three examples are the same. Use `master` instead of `main` if you ``` - Via `release.config.cjs` file: + ```js /** * @type {import('semantic-release').GlobalConfig} @@ -72,9 +76,10 @@ $ semantic-release --branches next ``` :::note + - CLI arguments take precedence over options configured in the configuration file. - Plugin options cannot be configured through CLI arguments. See [`plugins`](#plugins) for details. -::: + ::: ## Options @@ -107,6 +112,7 @@ The branches on which releases should happen. By default **semantic-release** wi - pre-releases to the `alpha` distribution channel from the branch `alpha` if it exists :::note + - Branches configuration key accepts [**micromatch**](https://github.com/micromatch/micromatch?tab=readme-ov-file#matching-features) globs. - 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 `main` or `master` branch. - 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 rulesets](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets). diff --git a/src/content/docs/usage/running.md b/src/content/docs/usage/running.md index d634df9..5e8477b 100644 --- a/src/content/docs/usage/running.md +++ b/src/content/docs/usage/running.md @@ -1,6 +1,7 @@ --- title: "Running semantic-release" --- + How to run **semantic-release** in your CI pipeline using `npx`, including version pinning strategies and tradeoffs of local installation. ## Using npx (recommended) @@ -51,7 +52,7 @@ Since **semantic-release** isn't truly a development dependency, but rather a re - installing dependencies that could conflict with other development dependencies, like **commitlint** :::note -A tradeoff of running via `npx` instead of installing locally is that the full **semantic-release** dependency graph is not pinned by your project's lockfile. +A tradeoff of running via `npx` instead of installing locally is that the full **semantic-release** dependency graph is not pinned by your project's lockfile. The [version pinning strategies](#notes) above help mitigate this. -::: \ No newline at end of file +::: From 4b1000c6d65287446a4872626b5600840211e064 Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 1 May 2026 23:17:13 +0100 Subject: [PATCH 10/25] feat(docs): enhance release steps documentation with detailed lifecycle overview and optional steps --- src/content/docs/foundation/steps.md | 48 ++++++++++++++++++---------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/src/content/docs/foundation/steps.md b/src/content/docs/foundation/steps.md index a43f4c7..0916ebe 100644 --- a/src/content/docs/foundation/steps.md +++ b/src/content/docs/foundation/steps.md @@ -2,33 +2,49 @@ title: Release Steps --- -This page explains the release lifecycle that runs when `semantic-release` is executed. If you are new to the overall model, read [How it Works](/foundation/how-it-works/) first. +This page explains the release steps that make up a `semantic-release` run. -## Lifecycle overview +- A **release lifecycle** is the full recurring process that starts from the previous release state and ends with the next release state. +- **Release steps** are the individual phases within one run of that lifecycle. +- Some release steps expose **lifecycle hooks** that plugins can bind to. +- Plugins participate by exposing **lifecycle methods** such as `analyzeCommits` or `publish`. + +If you are new to the overall model, read [How it Works](/foundation/how-it-works/) first. + +## Release step sequence After tests pass and `semantic-release` starts, it evaluates the repository state and executes release steps in a fixed order. -| Step | Purpose | -| ----------------- | --------------------------------------------------------------- | -| Verify Conditions | Confirm required configuration and credentials are available. | -| Get Last Release | Find the most recent release by reading Git tags/history. | -| Analyze Commits | Determine whether to release and which version type to produce. | -| Verify Release | Validate the computed release metadata before publishing. | -| Generate Notes | Build release notes for the commits included in this release. | -| Create Git Tag | Tag the release version in Git. | -| Prepare | Perform pre-publish updates such as assets or files. | -| Publish | Publish artifacts to configured destinations and channels. | -| Notify | Report success or failure through provider integrations. | +| Release Step | Lifecycle Hook(s) | Purpose | +| ----------------- | ------------------ | --------------------------------------------------------------- | +| Verify Conditions | `verifyConditions` | Confirm required configuration and credentials are available. | +| Get Last Release | None | Find the most recent release by reading Git tags and history. | +| Analyze Commits | `analyzeCommits` | Determine whether to release and which version type to produce. | +| Verify Release | `verifyRelease` | Validate the computed release metadata before publishing. | +| Generate Notes | `generateNotes` | Build release notes for the commits included in this release. | +| Create Git Tag | None | Tag the release version in Git. | +| Prepare | `prepare` | Perform pre-publish updates such as assets or files. | +| Publish | `publish` | Publish artifacts to configured destinations and channels. | +| Notify | `success`, `fail` | Report success or failure through provider integrations. | The order is important. A failure in an early step prevents later steps from running. +## Optional and conditional steps + +Not every release-related action appears in the always-run sequence above. + +- Some release steps are core-only and do not expose lifecycle hooks. `Get Last Release` is the clearest example. +- Some steps expose more than one lifecycle hook. `Notify` is implemented through the `success` and `fail` hooks. +- Some hooks are conditional. `addChannel` is used for channel management flows, such as associating a release with a distribution channel, and only runs when that behavior is needed. + ## How steps are implemented -Each lifecycle step is implemented by plugins. Some steps are optional, some are required for a valid release pipeline. +Release steps are executed by a combination of core behavior and plugins. +- Core handles some behavior directly, including steps that are not exposed as hooks - `analyzeCommits` is required to decide version impact -- Most other steps depend on which plugins you configure -- If multiple plugins implement the same step, they execute in plugin order +- Most hook-backed steps depend on which plugins you configure +- If multiple plugins implement the same lifecycle hook, they execute in plugin order For plugin responsibilities and execution details, see [Plugins](/foundation/plugins/). From 159bb21345221f971913e490d16ae30526b7ce4b Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 1 May 2026 23:25:02 +0100 Subject: [PATCH 11/25] feat(docs): clarify plugin lifecycle hooks and update links in configuration documentation --- src/content/docs/foundation/how-it-works.md | 2 +- src/content/docs/usage/configuration.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/foundation/how-it-works.md b/src/content/docs/foundation/how-it-works.md index fb2f803..693c60d 100644 --- a/src/content/docs/foundation/how-it-works.md +++ b/src/content/docs/foundation/how-it-works.md @@ -24,7 +24,7 @@ If no commits since the last release carry a recognized type, no release is publ Tools like [commitizen](https://github.com/commitizen/cz-cli) and [commitlint](https://github.com/conventional-changelog/commitlint) can help contributors author valid commit messages consistently. -For deeper details on commit analysis and lifecycle phases, see [Release Steps](/foundation/steps/) and [Plugins](/foundation/plugins/). +For deeper details on commit analysis, release steps, and plugin hooks, see [Release Steps](/foundation/steps/) and [Plugins](/foundation/plugins/). ## Why CI is central diff --git a/src/content/docs/usage/configuration.md b/src/content/docs/usage/configuration.md index 8bc13ec..7fb30b5 100644 --- a/src/content/docs/usage/configuration.md +++ b/src/content/docs/usage/configuration.md @@ -148,7 +148,7 @@ The `tagFormat` must contain the `version` variable exactly once and compile to **default**: `['@semantic-release/commit-analyzer', '@semantic-release/release-notes-generator', '@semantic-release/npm', '@semantic-release/github']`\ **CLI arguments**: `-p`, `--plugins` -Define the list of plugins to use. Plugins will run in series, in the order defined, for each [steps](/intro/#release-steps) if they implement it. +Define the list of plugins to use. Plugins will run in series, in the order defined, for each [release step](/foundation/steps/) whose lifecycle hook they implement. Plugins configuration can defined by wrapping the name and an options object in an array. @@ -156,7 +156,7 @@ Plugins configuration can defined by wrapping the name and an options object in While plugins can be listed by name via the `--plugins` CLI argument, individual plugin options cannot be configured through CLI arguments. If you need to configure plugin options beyond specifying which plugins to use, a [configuration file](#configuration-file) is required. ::: -See [Plugins](/usage/plugins) for more details. +See [Plugins](/foundation/plugins/) for more details. ### `dryRun` @@ -164,7 +164,7 @@ See [Plugins](/usage/plugins) for more details. **default**: `false` if running in a CI environment, `true` otherwise\ **CLI arguments**: `-d`, `--dry-run` -The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following steps: prepare, publish, addChannel, success and fail. In addition to this it prints the next version and release notes to the console. +The objective of the dry-run mode is to get a preview of the pending release. Dry-run mode skips the following lifecycle hooks: `prepare`, `publish`, `addChannel`, `success`, and `fail`. In addition to this it prints the next version and release notes to the console. :::note The Dry-run mode verifies the repository push permission, even though nothing will be pushed. The verification is done to help user to figure out potential configuration issues. From e16d7ac655dbfa4dfb5d3609715f3f12df3dcf0c Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 1 May 2026 23:29:58 +0100 Subject: [PATCH 12/25] feat(docs): enhance plugins documentation with detailed lifecycle hooks and improved descriptions --- src/content/docs/foundation/plugins.md | 38 ++++++++++++++------------ 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/src/content/docs/foundation/plugins.md b/src/content/docs/foundation/plugins.md index 0c9d133..f9878c5 100644 --- a/src/content/docs/foundation/plugins.md +++ b/src/content/docs/foundation/plugins.md @@ -2,25 +2,29 @@ title: "Plugins" --- -Each [release step](../../#release-steps) is implemented by configurable plugins. This allows for support of different [commit message formats](../../#commit-message-format), release note generators and publishing platforms. +Plugins let `semantic-release` extend release steps through configurable lifecycle methods. Core owns the release lifecycle, exposes lifecycle hooks for selected release steps, and invokes plugin methods bound to those hooks. -A plugin is a npm module that can implement one or more of the following steps: +This allows for support of different [commit message formats](../../#commit-message-format), release note generators, and publishing platforms. -| Step | Required | Description | -| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `verifyConditions` | No | Responsible for verifying conditions necessary to proceed with the release: configuration is correct, authentication token are valid, etc... | -| `analyzeCommits` | Yes | Responsible for determining the type of the next release (`major`, `minor` or `patch`). If multiple plugins with a `analyzeCommits` step are defined, the release type will be the highest one among plugins output. | -| `verifyRelease` | No | Responsible for verifying the parameters (version, type, dist-tag etc...) of the release that is about to be published. | -| `generateNotes` | No | Responsible for generating the content of the release note. If multiple plugins with a `generateNotes` step are defined, the release notes will be the result of the concatenation of each plugin output. | -| `prepare` | No | Responsible for preparing the release, for example creating or updating files such as `package.json`, `CHANGELOG.md`, documentation or compiled assets and pushing a commit. | -| `publish` | No | Responsible for publishing the release. | -| `addChannel` | No | Responsible for adding a release channel (e.g. adding an npm dist-tag to a release). | -| `success` | No | Responsible for notifying of a new release. | -| `fail` | No | Responsible for notifying of a failed release. | +A plugin is a npm module that can implement one or more lifecycle methods for the following hooks: -Release steps will run in that order. At each step, **semantic-release** will run every plugin in the [`plugins` array](plugins.md#plugins-declaration-and-execution-order), as long as the plugin implements the step. +| Lifecycle Hook | Related Release Step | Required | Description | +| ------------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `verifyConditions` | Verify Conditions | No | Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on. | +| `analyzeCommits` | Analyze Commits | Yes | Determine the type of the next release (`major`, `minor`, or `patch`). If multiple plugins implement `analyzeCommits`, the highest release type returned wins. | +| `verifyRelease` | Verify Release | No | Verify the parameters of the release that is about to be published, such as version, type, or distribution tag. | +| `generateNotes` | Generate Notes | No | Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output. | +| `prepare` | Prepare | No | Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit. | +| `publish` | Publish | No | Publish the release. | +| `addChannel` | Optional channel step | No | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag. | +| `success` | Notify | No | Notify consumers or maintainers after a successful release. | +| `fail` | Notify | No | Notify consumers or maintainers after a failed release. | -**Note:** If no plugin with a `analyzeCommits` step is defined `@semantic-release/commit-analyzer` will be used. +For each [release step](/foundation/steps/), **semantic-release** runs every plugin in the [`plugins` array](plugins.md#plugins-declaration-and-execution-order) that implements the hook for that step. + +Not every release step is hook-backed. For example, core handles `Get Last Release` and `Create Git Tag` directly. `addChannel` is a special-case hook used only when channel management applies. + +**Note:** If no plugin with an `analyzeCommits` method is defined `@semantic-release/commit-analyzer` will be used. ## Plugins installation @@ -59,7 +63,7 @@ Each plugin must be configured with the [`plugins` options](configuration.md#plu **Note:** If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it. -For each [release step](../../#release-steps) the plugins that implement that step will be executed in the order in which they are defined. +For each [release step](/foundation/steps/), the plugins that implement that step's lifecycle hook will be executed in the order in which they are defined. ```json { @@ -80,7 +84,7 @@ With this configuration **semantic-release** will: - execute the `prepare` implementation of `@semantic-release/npm` then `@semantic-release/git` - execute the `publish` implementation of `@semantic-release/npm` -Order is first determined by release steps (such as `verifyConditions` → `analyzeCommits`). At each release step, plugins are executed in the order in which they are defined. +Order is first determined by release steps (such as `Verify Conditions` → `Analyze Commits`). At each release step, plugins are executed in the order in which they are defined. ## Plugin options configuration From d3467b209550b420592bbc0983ac8fbae2856378 Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 15 May 2026 20:11:43 +0100 Subject: [PATCH 13/25] feat(docs): improve formatting of release steps table for clarity and consistency --- src/content/docs/foundation/steps.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/content/docs/foundation/steps.md b/src/content/docs/foundation/steps.md index 0916ebe..cb0ceef 100644 --- a/src/content/docs/foundation/steps.md +++ b/src/content/docs/foundation/steps.md @@ -15,27 +15,28 @@ If you are new to the overall model, read [How it Works](/foundation/how-it-work After tests pass and `semantic-release` starts, it evaluates the repository state and executes release steps in a fixed order. -| Release Step | Lifecycle Hook(s) | Purpose | -| ----------------- | ------------------ | --------------------------------------------------------------- | -| Verify Conditions | `verifyConditions` | Confirm required configuration and credentials are available. | -| Get Last Release | None | Find the most recent release by reading Git tags and history. | -| Analyze Commits | `analyzeCommits` | Determine whether to release and which version type to produce. | -| Verify Release | `verifyRelease` | Validate the computed release metadata before publishing. | -| Generate Notes | `generateNotes` | Build release notes for the commits included in this release. | -| Create Git Tag | None | Tag the release version in Git. | -| Prepare | `prepare` | Perform pre-publish updates such as assets or files. | -| Publish | `publish` | Publish artifacts to configured destinations and channels. | -| Notify | `success`, `fail` | Report success or failure through provider integrations. | +| Release Step | Lifecycle Hook(s) | Purpose | +| ---------------------- | ------------------ | --------------------------------------------------------------- | +| Verify Conditions | `verifyConditions` | Confirm required configuration and credentials are available. | +| Get Last Release | None | Find the most recent release by reading Git tags and history. | +| Analyze Commits | `analyzeCommits` | Determine whether to release and which version type to produce. | +| Verify Release | `verifyRelease` | Validate the computed release metadata before publishing. | +| Generate Notes | `generateNotes` | Build release notes for the commits included in this release. | +| Create Git Tag | None | Tag the release version in Git. | +| Add Channel (Optional) | `addChannel` | Associate the release with a distribution channel when needed. | +| Prepare | `prepare` | Perform pre-publish updates such as assets or files. | +| Publish | `publish` | Publish artifacts to configured destinations and channels. | +| Notify | `success`, `fail` | Report success or failure through provider integrations. | The order is important. A failure in an early step prevents later steps from running. ## Optional and conditional steps -Not every release-related action appears in the always-run sequence above. +Not every release step in the table above runs on every release. - Some release steps are core-only and do not expose lifecycle hooks. `Get Last Release` is the clearest example. - Some steps expose more than one lifecycle hook. `Notify` is implemented through the `success` and `fail` hooks. -- Some hooks are conditional. `addChannel` is used for channel management flows, such as associating a release with a distribution channel, and only runs when that behavior is needed. +- Some release steps are conditional. The `Add Channel` release step is an example; it runs only when channel management behavior is needed. ## How steps are implemented From 461dafe97dfc94a529a1f6f07e6f2aff5acbc4e8 Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 15 May 2026 20:31:14 +0100 Subject: [PATCH 14/25] feat(docs): update considerations documentation for clarity and consistency --- src/content/docs/foundation/considerations.md | 28 ++++++++++++++----- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/src/content/docs/foundation/considerations.md b/src/content/docs/foundation/considerations.md index e63331b..a59e118 100644 --- a/src/content/docs/foundation/considerations.md +++ b/src/content/docs/foundation/considerations.md @@ -6,35 +6,49 @@ title: Considerations - an opinionated release tool - a tool to simplify versioning releases semantically first, automating steps related to a release process second -- a tool that encourages engineering practices that support delivering high quality at a sustainable pace (continuous deployment/release, trunk based deployment) +- a tool that encourages engineering practices that support delivering high quality at a sustainable pace (continuous deployment/release, trunk-based development) -## Are you interested in **semantic-release** because of our primary or secondary goals +## What is your primary goal? If your primary attraction is for automatic release note generation rather than semantic versioning, you may want to reconsider if **semantic-release** is the right fit for your goals. +:::tip[Recommendation] +Adopt **semantic-release** when semantic versioning is your primary objective, with release-step automation as a secondary benefit. +::: + ## Do you actually need semantic versioning? The use of the word "semantic" in the term "semantic versioning" has the intent that the structure of the version conveys specific meaning. -Consult https://semver.org/ for details about the details of the specific meaning, but keep in mind that the semantics are from the perspective of a consumer. +Consult https://semver.org/ for details of that meaning, but keep in mind that the semantics are from the perspective of a consumer. Semantic versioning is most useful for software releases that are consumed programmatically. Common examples are libraries/packages consumed as dependencies. Base Docker images can also fall in this category because they are consumed in a way that other layers build on top of them. -Applications that are deployed directly to a runtime environment lack an audience to benefit from the benefits of semantic versioning. +Applications that are deployed directly to a runtime environment lack an audience to benefit from semantic versioning. Docker images that are published to a registry only for the purpose of deploying directly to a runtime environment fall into this category, even though they are a published asset. Often, using the git SHA as the version for such assets is a better choice than versioning them semantically. +:::tip[Recommendation] +Prioritize semantic versioning for artifacts consumed as dependencies; for directly deployed artifacts, consider using git SHAs instead. +::: + ## Can you simplify the release steps automated by **semantic-release**? Updating the version in the `package.json` of an npm package or providing release notes in a `CHANGELOG.md` file are popular release steps that can be enabled with **semantic-release** using the [changelog](https://github.com/semantic-release/changelog) and [git](https://github.com/semantic-release/git) plugins. However, those two plugins are intentionally _not_ included in the default configuration of **semantic-release** because -[they are not necessary for **semantic-release** to function](https://semantic-release.gitbook.io/semantic-release/support/faq#it-is-not-needed-for-semantic-release-to-do-its-job) -and [making commits during the release process adds significant complexity](https://semantic-release.gitbook.io/semantic-release/support/faq#making-commits-during-the-release-process-adds-significant-complexity). +[they are not necessary for **semantic-release** to function](/support/faq#it-is-not-needed-for-semantic-release-to-do-its-job) +and [making commits during the release process adds significant complexity](/support/faq#making-commits-during-the-release-process-adds-significant-complexity). Please consider the trade-offs of adding those plugins to your release configuration for potentially unnecessary goals. +:::tip[Recommendation] +Keep your configuration minimal and only add release-time commits when there is a clear, justified need. +::: + ## Is the branching strategy of your project supported by **semantic-release**? -[supported branching strategies](./supported-branching.md) +Before adopting **semantic-release**, confirm that your team's branching model is compatible. + +See [supported branching strategies](/foundation/supported-branching) From e26b8bf716bd5b2256792cdc29dfcef2f4845ac9 Mon Sep 17 00:00:00 2001 From: babblebey Date: Fri, 15 May 2026 21:26:04 +0100 Subject: [PATCH 15/25] feat(docs): restructure supported branching models documentation for clarity and recommendations --- .../docs/foundation/supported-branching.md | 89 ++++++++++++------- 1 file changed, 59 insertions(+), 30 deletions(-) diff --git a/src/content/docs/foundation/supported-branching.md b/src/content/docs/foundation/supported-branching.md index 202d569..95da966 100644 --- a/src/content/docs/foundation/supported-branching.md +++ b/src/content/docs/foundation/supported-branching.md @@ -2,62 +2,91 @@ title: Supported Branching Models --- -## Trunk Based Development +This page summarizes branching models that align well with **semantic-release** and those that are officially unsupported. -- https://trunkbaseddevelopment.com/ -- https://minimumcd.org/minimumcd/tbd/ +:::tip[Recommendation] +Default to workflows that keep changes flowing to a stable trunk quickly and continuously. +::: -### Committing Straight to the Trunk +## Supported Branching Models -- https://trunkbaseddevelopment.com/#trunk-based-development-for-smaller-teams -- https://trunkbaseddevelopment.com/committing-straight-to-the-trunk/ +These models align with the delivery and release assumptions built into **semantic-release**. -### Short-Lived Feature Branches +### Trunk-Based Development -- https://trunkbaseddevelopment.com/#scaled-trunk-based-development -- https://trunkbaseddevelopment.com/short-lived-feature-branches/ +- [Trunk-Based Development](https://trunkbaseddevelopment.com/) +- [MinimumCD: Trunk-Based Development](https://minimumcd.org/minimumcd/tbd/) -### Continuous Integration +#### Committing Straight to Trunk -- https://minimumcd.org/minimumcd/ci/ +- [Trunk-Based Development for Smaller Teams](https://trunkbaseddevelopment.com/#trunk-based-development-for-smaller-teams) +- [Committing Straight to the Trunk](https://trunkbaseddevelopment.com/committing-straight-to-the-trunk/) -### Continuous Deployment/Release +#### Short-Lived Feature Branches -- https://trunkbaseddevelopment.com/continuous-delivery/#continuous-deployment +- [Scaled Trunk-Based Development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development) +- [Short-Lived Feature Branches](https://trunkbaseddevelopment.com/short-lived-feature-branches/) -## GitHub Flow +#### Continuous Integration -- https://githubflow.github.io/ -- https://docs.github.com/en/get-started/using-github/github-flow +- [MinimumCD: Continuous Integration](https://minimumcd.org/minimumcd/ci/) + +#### Continuous Deployment/Release + +- [Continuous Deployment](https://trunkbaseddevelopment.com/continuous-delivery/#continuous-deployment) + +:::tip[Recommendation] +Choose a trunk-based workflow that keeps branch lifetime short and integration frequent. +::: + +### GitHub Flow + +- [GitHub Docs: GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow) +- [GitHub Flow](https://githubflow.github.io/) + +:::tip[Recommendation] +GitHub Flow is a practical fit when pull requests are short-lived and releases are frequent. +::: ## Officially Unsupported Branching Models -### Trunk Based Development: Branch for release +These models conflict with the default expectations of **semantic-release** and are not supported by the project team. + +### Trunk-Based Development: Branch for Release -https://trunkbaseddevelopment.com/branch-for-release/ +- [Branch for Release](https://trunkbaseddevelopment.com/branch-for-release/) -exception: +Exception: -- https://trunkbaseddevelopment.com/branch-for-release/#late-creation-of-release-branches - - our maintenance release is an example of this approach +- [Late Creation of Release Branches](https://trunkbaseddevelopment.com/branch-for-release/#late-creation-of-release-branches) - _our maintenance release is an example of this approach_ -### git-flow +### Git Flow: Long-Lived Branch Orchestration (develop/release/hotfix) -- https://nvie.com/posts/a-successful-git-branching-model/ -- https://jeffkreeftmeijer.com/git-flow/ +- [A Successful Git Branching Model](https://nvie.com/posts/a-successful-git-branching-model/) +- [Why You Should Not Use Git Flow](https://jeffkreeftmeijer.com/git-flow/) -Even if this is strategy that you find useful for the applications you are building, which [the original author of the git-flow branching model recommends against](https://nvie.com/posts/a-successful-git-branching-model/), -we do not recommend this branching model when releasing artifacts with **semantic-release**. +Even if this is a strategy that you find useful for the applications you are building, [the original author of the git-flow branching model recommends against it](https://nvie.com/posts/a-successful-git-branching-model/) for that context, +we do not recommend this long-lived branch orchestration pattern when releasing artifacts with **semantic-release**. While the [same reflection](https://nvie.com/posts/a-successful-git-branching-model/) that recommends against using git-flow for web apps suggests that it may still be a good fit for explicitly versioned software, **semantic-release** is built with Continuous Deployment/Release in mind instead. -While some have found that the [Pre-release workflow](./workflow-configuration.md#pre-release-branches) enabled by **semantic-release** can be used to _simulate_ a git-flow-like workflow, -it is also worth noting that workflow is not intended for such a use case and requests for support when attempting to use it that way will be closed by our team. +While some have found that the [Pre-release workflow](/foundation/workflow-configuration/#prerelease) enabled by **semantic-release** can be used to _simulate_ a git-flow-like workflow, +it is also worth noting that this orchestration pattern is not an intended use case and requests for support when attempting to use it that way will be closed by our team. + +:::tip[Recommendation] +Avoid Git flow-style long-lived branch orchestration when using **semantic-release**. +::: ### Workflows that Release for Testing Before Promotion to a Stable Release -- https://trunkbaseddevelopment.com/styles/#the-importance-of-a-local-build +- [The Importance of a Local Build](https://trunkbaseddevelopment.com/styles/#the-importance-of-a-local-build) + +:::tip[Recommendation] +Prefer workflows where confidence comes from CI quality signals, with production release as the promotion event. +::: ### Monorepos -While not specifically a branching strategy, +While monorepos are not specifically a branching strategy, they are also not an officially supported **semantic-release** setup at this time. +That said, the same branching and release principles described on this page still apply to releasable artifacts in a monorepo. +For teams that choose this approach, community plugins can enable monorepo support for now. From 1674e6ac139a2030745dcb141eda96aeda839376 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 01:16:11 +0100 Subject: [PATCH 16/25] feat(docs): correct formatting and improve clarity in release workflow configuration documentation --- .../docs/foundation/workflow-configuration.md | 92 +++++++++++-------- 1 file changed, 55 insertions(+), 37 deletions(-) diff --git a/src/content/docs/foundation/workflow-configuration.md b/src/content/docs/foundation/workflow-configuration.md index cba34f6..699cabd 100644 --- a/src/content/docs/foundation/workflow-configuration.md +++ b/src/content/docs/foundation/workflow-configuration.md @@ -1,40 +1,44 @@ --- -title: "Release Workflow configuration" +title: "Release Workflow Configuration" --- -**semantic-release** enables managing and automating complex release workflow, based on multiple Git branches and distribution channels. This enables: +**semantic-release** enables managing and automating complex release workflows, based on multiple Git branches and distribution channels. This enables: - Distributing certain releases to a particular group of users via distribution channels -- Managing the availability of releases on distribution channels via branches merge +- Managing the availability of releases on distribution channels via branch merges - 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/#release-workflow) for detailed examples. -The release workflow is configured via the [branches option](configuration.md#branches) which accepts a single or an array of branch definitions. Each branch can be defined either as a string, a [glob](https://github.com/micromatch/micromatch#matching-features) or an object. For string and glob definitions each [property](workflow-configuration.md#branches-properties) will be defaulted. +The release workflow is configured via the [branches option](/usage/configuration/#branches), which accepts either a single branch definition or an array of branch definitions. Each branch can be defined as a string, a [glob](https://github.com/micromatch/micromatch#matching-features), or an object. For string and glob definitions, defaults are applied to each [property](#branch-properties). A branch can be defined as one of three types: -- [release](workflow-configuration.md#release-branches): to make releases on top of the last version released -- [maintenance](workflow-configuration.md#maintenance-branches): to make releases on top of an old release -- [pre-release](workflow-configuration.md#pre-release-branches): to make pre-releases +- [release](#release-branches): to make releases on top of the last version released +- [maintenance](#maintenance-branches): to make releases on top of an old release +- [pre-release](#pre-release-branches): to make pre-releases -The type of the branch is automatically determined based on naming convention and/or [properties](workflow-configuration.md#branches-properties). +The type of the branch is automatically determined based on naming conventions and/or [properties](#branch-properties). -## Branches properties +## Branch Properties | Property | Branch type | Description | Default | | ------------ | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -| `name` | All | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](workflow-configuration.md#name). | - The value itself if defined as a `String` or the matching branches name if defined as a glob. | -| `channel` | All | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](workflow-configuration.md#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones. | -| `range` | [maintenance](workflow-configuration.md#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](workflow-configuration.md#range). | The value of `name`. | -| `prerelease` | [pre-release](workflow-configuration.md#pre-release-branches) only | **Required.** The pre-release denotation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](workflow-configuration.md#prerelease). | - | +| `name` | All | **Required.** The Git branch holding the commits to analyze and the code to release. See [name](#name). | - The value itself if defined as a `String` or the matching branches name if defined as a glob. | +| `channel` | All | The distribution channel on which to publish releases from this branch. Set to `false` to force the default distribution channel instead of using the default. See [channel](#channel). | `undefined` for the first release branch, the value of `name` for subsequent ones. | +| `range` | [maintenance](#maintenance-branches) only | **Required unless `name` is formatted like `N.N.x` or `N.x` (`N` is a number).** The range of [semantic versions](https://semver.org) to support on this branch. See [range](#range). | The value of `name`. | +| `prerelease` | [pre-release](#pre-release-branches) only | **Required.** The pre-release denotation to append to [semantic versions](https://semver.org) released from this branch. See [prerelease](#prerelease). | - | -### name +### `name` + +**type**: `String`, `Glob`\ +**branch type**: All\ +**default**: The value itself if defined as a `String`, or the matching branch name if defined as a glob. A `name` is required for any type of branch. It can be defined as a [glob](https://github.com/micromatch/micromatch#matching-features) in which case the definition will be expanded to one per matching branch existing in the repository. -If `name` doesn't match to any branch existing in the repository, the definition will be ignored. For example the default configuration includes the definition `next` and `next-major` which will become active only when the branches `next` and/or `next-major` are created in the repository. This allow to define your workflow once with all potential branches you might use and have the effective configuration evolving as you create new branches. +If `name` doesn't match any branch that exists in the repository, the definition will be ignored. For example, the default configuration includes the definitions `next` and `next-major`, which become active only when the branches `next` and/or `next-major` are created in the repository. This allows you to define your workflow once with all potential branches you might use and have the effective configuration evolve as you create new branches. For example the configuration `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next']` will be expanded as: @@ -49,9 +53,13 @@ For example the configuration `['+([0-9])?(.{+([0-9]),x}).x', 'master', 'next']` } ``` -### channel +### `channel` + +**type**: `String`, `Boolean`\ +**branch type**: All\ +**default**: `undefined` for the first release branch; the value of `name` for subsequent ones. -The `channel` can be defined for any branch type. By default releases will be done on the default distribution channel (for example the `@latest` [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm) for the first [release branch](workflow-configuration.md#release-branches) and on a distribution channel named based on the branch `name` for any other branch. If the `channel` property is set to `false` the default channel will be used. +The `channel` can be defined for any branch type. By default releases will be done on the default distribution channel (for example the `@latest` [dist-tag](https://docs.npmjs.com/cli/dist-tag) for npm) for the first [release branch](#release-branches) and on a distribution channel named based on the branch `name` for any other branch. If the `channel` property is set to `false` the default channel will be used. The value of `channel`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available. @@ -66,9 +74,13 @@ For example the configuration `['master', {name: 'next', channel: 'channel-${nam } ``` -### range +### `range` -A `range` only applies to maintenance branches, is required and must be formatted like `N.N.x` or `N.x` (`N` is a number). In case the `name` is formatted as a range (for example `1.x` or `1.5.x`) the branch will be considered a maintenance branch and the `name` value will be used for the `range`. +**type**: `String`\ +**branch type**: [Maintenance](#maintenance-branches) only\ +**default**: The value of `name`. + +A `range` only applies to maintenance branches, is required (unless `name` is formatted like `N.N.x` or `N.x`), and must be formatted like `N.N.x` or `N.x` (`N` is a number). In case the `name` is formatted as a range (for example `1.x` or `1.5.x`) the branch will be considered a maintenance branch and the `name` value will be used for the `range`. For example the configuration `['1.1.x', '1.2.x', 'master']` will be expanded as: @@ -82,9 +94,13 @@ For example the configuration `['1.1.x', '1.2.x', 'master']` will be expanded as } ``` -### prerelease +### `prerelease` + +**type**: `String`, `Boolean`\ +**branch type**: [Pre-release](#pre-release-branches) only\ +**default**: - -A `prerelease` property applies only to pre-release branches and the `prerelease` value must be valid per the [Semantic Versioning Specification](https://semver.org/#spec-item-9). It will determine the name of versions (for example if `prerelease` is set to `beta` the version be formatted like `2.0.0-beta.1`, `2.0.0-beta.2` etc...). If the `prerelease` property is set to `true` the `name` value will be used. +A `prerelease` property applies only to pre-release branches and is required. The `prerelease` value must be valid per the [Semantic Versioning Specification](https://semver.org/#spec-item-9). It determines the format of versions (for example, if `prerelease` is set to `beta`, versions will be formatted like `2.0.0-beta.1`, `2.0.0-beta.2`, etc.). If the `prerelease` property is set to `true`, the `name` value will be used. The value of `prerelease`, if defined as a string, is generated with [Lodash template](https://lodash.com/docs#template) with the variable `name` available. @@ -106,22 +122,24 @@ For example the configuration `['master', {name: 'pre/rc', prerelease: '${name.r A release branch is the base type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org), optionally on a specific distribution channel. Distribution channels (for example [npm dist-tags](https://docs.npmjs.com/cli/dist-tag) or [Chrome release channels](https://www.chromium.org/getting-involved/dev-channel)) are a way to distribute new releases only to a subset of users in order to get early feedback. Later on, those releases can be added to the general distribution channel to be made available to all users. -**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release branch to another](workflow-configuration.md#merging-into-a-release-branch). +**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release branch to another](#merging-into-a-release-branch). -A project must define a minimum of 1 release branch and can have a maximum of 3. The order of the release branch definitions is significant, as versions released on a given branch must always be higher than the last release made on the previous branch. This allow to avoid situation that would lead to an attempt to publish releases with the same version number but different codebase. When multiple release branches are configured and a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them. +A project must define a minimum of 1 release branch and can have a maximum of 3. The order of the release branch definitions is significant, as versions released on a given branch must always be higher than the last release made on the previous branch. This allows avoiding situations that would lead to attempts to publish releases with the same version number but different codebases. When multiple release branches are configured and a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them. -**Note:** With **semantic-release** as with most package managers, a release version must be unique, independently of the distribution channel on which it is available. +:::note +With **semantic-release** as with most package managers, a release version must be unique, independently of the distribution channel on which it is available. +::: -See [publishing on distribution channels recipe](../recipes/release-workflow/distribution-channels.md) for a detailed example. +See [publishing on distribution channels recipe](/recipes/release-workflow/distribution-channels) for a detailed example. #### Pushing to a release branch With the configuration `"branches": ["master", "next"]`, if the last release published from `master` is `1.0.0` and the last one from `next` is `2.0.0` then: - Only versions in range `1.x.x` can be published from `master`, so only `fix` and `feat` commits can be pushed to `master` -- Once `next` get merged into `master` the release `2.0.0` will be made available on the channel associated with `master` and both `master` and `next` will accept any commit type +- Once `next` gets merged into `master`, the release `2.0.0` will be made available on the channel associated with `master`, and both `master` and `next` will accept any commit type -This verification prevent scenario such as: +This verification prevents scenarios such as: 1. Create a `feat` commit on `next` which triggers the release of version `1.0.0` on the `next` channel 2. Merge `next` into `master` which adds `1.0.0` on the default channel @@ -134,28 +152,28 @@ In step 4 **semantic-release** will throw an `EINVALIDNEXTVERSION` error to prev When merging commits associated with a release from one release branch to another, **semantic-release** will make the corresponding version available on the channel associated with the target branch. -When merging commits not associated with a release, commits from a [maintenance branch](workflow-configuration.md#maintenance-branches) or commits from a [pre-release branch](workflow-configuration.md#pre-release-branches) **semantic-release** will treat them as [pushed commits](workflow-configuration.md#pushing-to-a-release-branch) and publish a new release if necessary. +When merging commits not associated with a release, commits from a [maintenance branch](#maintenance-branches) or commits from a [pre-release branch](#pre-release-branches) **semantic-release** will treat them as [pushed commits](#pushing-to-a-release-branch) and publish a new release if necessary. ### Maintenance branches A maintenance branch is a type of branch used by **semantic-release** that allows to publish releases with a [semantic version](https://semver.org) on top of the codebase of an old release. This is useful when you need to provide fixes or features to users who cannot upgrade to the last version of your package. -A maintenance branch is characterized by a range which defines the versions that can be published from it. The [`range`](workflow-configuration.md#range) value of each maintenance branch must be unique across the project. +A maintenance branch is characterized by a range which defines the versions that can be published from it. The [`range`](#range) value of each maintenance branch must be unique across the project. **semantic-release** will always publish releases to a distribution channel specific to the range, so only the users who choose to use that particular line of versions will receive new releases. -Maintenance branches are always considered lower than [release branches](workflow-configuration.md#release-branches) and similarly to them, when a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them. +Maintenance branches are always considered lower than [release branches](#release-branches) and similarly to them, when a commit that would create a version conflict is pushed, **semantic-release** will not perform the release and will throw an `EINVALIDNEXTVERSION` error, listing the problematic commits and the valid branches on which to move them. -**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release or maintenance branch to another maintenance branch](workflow-configuration.md#merging-into-a-maintenance-branch), however only versions within the branch `range` can be merged. If a merged version is outside the maintenance branch `range`, **semantic-release** will not add to the corresponding channel and will throw an `EINVALIDMAINTENANCEMERGE` error. +**semantic-release** will automatically add releases to the corresponding distribution channel when code is [merged from a release or maintenance branch to another maintenance branch](#merging-into-a-maintenance-branch), however only versions within the branch `range` can be merged. If a merged version is outside the maintenance branch `range`, **semantic-release** will not add to the corresponding channel and will throw an `EINVALIDMAINTENANCEMERGE` error. -See [publishing maintenance releases recipe](../recipes/release-workflow/maintenance-releases.md) for a detailed example. +See [publishing maintenance releases recipe](/recipes/release-workflow/maintenance-releases) for a detailed example. #### Pushing to a maintenance branch With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last release published from `master` is `1.5.0` then: - Only versions in range `>=1.0.0 <1.1.0` can be published from `1.0.x`, so only `fix` commits can be pushed to `1.0.x` -- Only versions in range `>=1.1.0 <1.5.0` can be published from `1.x`, so only `fix` and `feat` commits can be pushed to `1.x` as long the resulting release is lower than `1.5.0` +- Only versions in range `>=1.1.0 <1.5.0` can be published from `1.x`, so only `fix` and `feat` commits can be pushed to `1.x` as long as the resulting release is lower than `1.5.0` - Once `2.0.0` is released from `master`, versions in range `>=1.1.0 <2.0.0` can be published from `1.x`, so any number of `fix` and `feat` commits can be pushed to `1.x` #### Merging into a maintenance branch @@ -169,15 +187,15 @@ With the configuration `"branches": ["1.0.x", "1.x", "master"]`, if the last rel ### Pre-release branches -A pre-release branch is a type of branch used by **semantic-release** that allows to publish releases with a [pre-release version](https://semver.org/#spec-item-9). Using a pre-release version allow to publish multiple releases with the same version. Those release will be differentiated via their identifiers (in `1.0.0-alpha.1` the identifier is `alpha.1`). This is useful when you need to work on a future major release that will include many breaking changes but you do not want to increment the version number for each breaking change commit. +A pre-release branch is a type of branch used by **semantic-release** that allows publishing releases with a [pre-release version](https://semver.org/#spec-item-9). Using a pre-release version allows publishing multiple releases with the same version. Those releases are differentiated via their identifiers (in `1.0.0-alpha.1`, the identifier is `alpha.1`). This is useful when you need to work on a future major release that will include many breaking changes, but you do not want to increment the version number for each breaking change commit. -A pre-release branch is characterized by the `prerelease` property that defines the static part of the version released (in `1.0.0-alpha.1` the static part fo the identifier is `alpha`). The [`prerelease`](workflow-configuration.md#prerelease) value of each pre-release branch must be unique across the project. +A pre-release branch is characterized by the `prerelease` property that defines the static part of the version released (in `1.0.0-alpha.1`, the static part of the identifier is `alpha`). The [`prerelease`](#prerelease) value of each pre-release branch must be unique across the project. **semantic-release** will always publish pre-releases to a specific distribution channel, so only the users who choose to use that particular line of versions will receive new releases. -When merging commits associated with an existing release, **semantic-release** will treat them as [pushed commits](workflow-configuration.md#pushing-to-a-pre-release-branch) and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch. +When merging commits associated with an existing release, **semantic-release** will treat them as [pushed commits](#pushing-to-a-pre-release-branch) and publish a new release if necessary, but it will never add those releases to the distribution channel corresponding to the pre-release branch. -See [publishing pre-releases recipe](../recipes/release-workflow/pre-releases.md) for a detailed example. +See [publishing pre-releases recipe](/recipes/release-workflow/pre-releases) for a detailed example. #### Pushing to a pre-release branch From 7a0f44a99c01080b5b2974628c463e7b1e70af9e Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 01:25:03 +0100 Subject: [PATCH 17/25] feat(docs): add link to 'Release from Trunk' in supported branching models documentation --- src/content/docs/foundation/supported-branching.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/content/docs/foundation/supported-branching.md b/src/content/docs/foundation/supported-branching.md index 95da966..e8194e7 100644 --- a/src/content/docs/foundation/supported-branching.md +++ b/src/content/docs/foundation/supported-branching.md @@ -16,6 +16,7 @@ These models align with the delivery and release assumptions built into **semant - [Trunk-Based Development](https://trunkbaseddevelopment.com/) - [MinimumCD: Trunk-Based Development](https://minimumcd.org/minimumcd/tbd/) +- [Release from Trunk](https://trunkbaseddevelopment.com/release-from-trunk/) #### Committing Straight to Trunk From 04f43943526d02e915104ece2e10a8233df40134 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 01:27:08 +0100 Subject: [PATCH 18/25] feat(docs): clarify release step examples and commit impact on versioning --- src/content/docs/foundation/steps.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/docs/foundation/steps.md b/src/content/docs/foundation/steps.md index cb0ceef..656910c 100644 --- a/src/content/docs/foundation/steps.md +++ b/src/content/docs/foundation/steps.md @@ -53,9 +53,11 @@ For plugin responsibilities and execution details, see [Plugins](/foundation/plu The `analyzeCommits` step is the decision point for whether a release is created. +The examples below assume the default Conventional Commits mapping and that the highest-impact commit type since the last release determines the version bump + - No relevant commits since the last release means no new release -- `fix` commits typically result in a patch release -- `feat` commits typically result in a minor release +- `fix` commits result in a patch release +- `feat` commits result in a minor release - `BREAKING CHANGE` results in a major release Commit parsing depends on your configured commit analyzer and presets. See [How it Works](/foundation/how-it-works/) for the conceptual model and [Configuration](/usage/configuration/) for setup details. From 5f240ec97be853203f26cbc3d3080150b429c897 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 01:56:36 +0100 Subject: [PATCH 19/25] feat(docs): enhance clarity and consistency in plugins documentation --- src/content/docs/foundation/plugins.md | 28 +++++++++++++++++--------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/src/content/docs/foundation/plugins.md b/src/content/docs/foundation/plugins.md index f9878c5..deca3f3 100644 --- a/src/content/docs/foundation/plugins.md +++ b/src/content/docs/foundation/plugins.md @@ -4,19 +4,19 @@ title: "Plugins" Plugins let `semantic-release` extend release steps through configurable lifecycle methods. Core owns the release lifecycle, exposes lifecycle hooks for selected release steps, and invokes plugin methods bound to those hooks. -This allows for support of different [commit message formats](../../#commit-message-format), release note generators, and publishing platforms. +This enables support for different [commit message conventions](/foundation/how-it-works/#the-core-model), release note generators, and publishing platforms. A plugin is a npm module that can implement one or more lifecycle methods for the following hooks: | Lifecycle Hook | Related Release Step | Required | Description | | ------------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `verifyConditions` | Verify Conditions | No | Verify conditions necessary to proceed with the release: configuration is correct, authentication tokens are valid, and so on. | -| `analyzeCommits` | Analyze Commits | Yes | Determine the type of the next release (`major`, `minor`, or `patch`). If multiple plugins implement `analyzeCommits`, the highest release type returned wins. | +| `analyzeCommits` | Analyze Commits | Yes | Determine the type of the next release (`major`, `minor`, or `patch`). This hook is required to decide the next release type. If multiple plugins implement `analyzeCommits`, the highest release type returned wins. | | `verifyRelease` | Verify Release | No | Verify the parameters of the release that is about to be published, such as version, type, or distribution tag. | | `generateNotes` | Generate Notes | No | Generate the content of the release note. If multiple plugins implement `generateNotes`, the release notes will be the concatenation of each plugin output. | | `prepare` | Prepare | No | Prepare the release, for example by creating or updating files such as `package.json`, `CHANGELOG.md`, documentation, or compiled assets and pushing a commit. | | `publish` | Publish | No | Publish the release. | -| `addChannel` | Optional channel step | No | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag. | +| `addChannel` | Add Channel (optional) | No | Assign the release to a distribution channel when channel management is needed, for example by adding an npm dist-tag. | | `success` | Notify | No | Notify consumers or maintainers after a successful release. | | `fail` | Notify | No | Notify consumers or maintainers after a failed release. | @@ -24,13 +24,15 @@ For each [release step](/foundation/steps/), **semantic-release** runs every plu Not every release step is hook-backed. For example, core handles `Get Last Release` and `Create Git Tag` directly. `addChannel` is a special-case hook used only when channel management applies. -**Note:** If no plugin with an `analyzeCommits` method is defined `@semantic-release/commit-analyzer` will be used. +:::note +If no plugin with an `analyzeCommits` method is defined `@semantic-release/commit-analyzer` will be used. +::: ## Plugins installation ### Default plugins -These four plugins are already part of **semantic-release** and are listed in order of execution. They do not have to be installed separately: +These four plugins are already part of **semantic-release** and are listed in order of execution. They should not be installed separately; installing them independently can result in conflicting behavior if multiple versions are present: ``` "@semantic-release/commit-analyzer" @@ -41,15 +43,19 @@ These four plugins are already part of **semantic-release** and are listed in or ### Additional plugins -[Additional plugins](../extending/plugins-list.md) have to be installed via npm: +[Additional plugins](/extending/plugins-list) should be provided to `npx` with `--package` when running `semantic-release`: ```bash -$ npm install @semantic-release/git @semantic-release/changelog -D +$ npx \ + --package semantic-release \ + --package @semantic-release/git \ + --package @semantic-release/changelog \ + semantic-release ``` ## Plugins declaration and execution order -Each plugin must be configured with the [`plugins` options](configuration.md#plugins) by specifying the list of plugins by npm module name. +Each plugin must be configured with the [`plugins` options](/usage/configuration/#plugins) by specifying the list of plugins by npm module name. ```json { @@ -61,7 +67,9 @@ Each plugin must be configured with the [`plugins` options](configuration.md#plu } ``` -**Note:** If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it. +:::note +If the `plugins` option is defined, it overrides the default plugin list, rather than merging with it. +::: For each [release step](/foundation/steps/), the plugins that implement that step's lifecycle hook will be executed in the order in which they are defined. @@ -112,4 +120,4 @@ Global plugin configuration can be defined at the root of the **semantic-release With this configuration: - All plugins will receive the `preset` option, which will be used by both `@semantic-release/commit-analyzer` and `@semantic-release/release-notes-generator` (and ignored by `@semantic-release/github` and `@semantic-release/git`) -- The `@semantic-release/github` plugin will receive the `assets` options (`@semantic-release/git` will not receive it and therefore will use it's default value for that option) +- The `@semantic-release/github` plugin will receive the `assets` option (`@semantic-release/git` will not receive it and therefore will use its default value for that option) From ac99674b89725f19d4a5e710a42cf9b1c14d5b74 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 22:00:17 +0100 Subject: [PATCH 20/25] feat(docs): clarify customization options for plugin configuration --- src/content/docs/foundation/plugins.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/foundation/plugins.md b/src/content/docs/foundation/plugins.md index deca3f3..e2fcb4e 100644 --- a/src/content/docs/foundation/plugins.md +++ b/src/content/docs/foundation/plugins.md @@ -55,7 +55,7 @@ $ npx \ ## Plugins declaration and execution order -Each plugin must be configured with the [`plugins` options](/usage/configuration/#plugins) by specifying the list of plugins by npm module name. +If you need to customize the default plugin set or execution order, configure the [`plugins` option](/usage/configuration/#plugins) by listing plugins by npm module name. ```json { From 3eb06f22df190ed71717cd4488a15d0858faa889 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 22:15:35 +0100 Subject: [PATCH 21/25] feat(docs): improve clarity and structure in shareable configurations documentation --- .../foundation/shareable-configurations.md | 32 ++++++++++++++++--- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/src/content/docs/foundation/shareable-configurations.md b/src/content/docs/foundation/shareable-configurations.md index 6fa08a3..0b2e146 100644 --- a/src/content/docs/foundation/shareable-configurations.md +++ b/src/content/docs/foundation/shareable-configurations.md @@ -1,9 +1,33 @@ --- -title: "Shareable configurations" +title: "Shareable Configurations" --- -A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a **semantic-release** configuration object. It allows for use of the same configuration across several projects. +A shareable configuration is an [npm](https://www.npmjs.com/) package that exports a reusable **semantic-release** configuration object. It lets teams define a common release workflow once and apply it across several projects. -The shareable configurations to use can be set with the [extends](configuration.md#extends) option. +## When to use it + +Use a shareable configuration when multiple repositories should follow the same release workflow and only need small project-specific overrides. + +In practice, a shareable configuration usually provides the base configuration, while each project keeps only the settings that differ locally. + +## How to use it + +The shareable configurations to use can be set with the [extends](/usage/configuration/#extends) option, using either an npm package name or a local file path. + +```json +{ + "extends": "@semantic-release/gitlab-config" +} +``` + +For example, a project can extend a shared base config and still override its own branches locally: + +```json +{ + "extends": "@semantic-release/gitlab-config", + "branches": ["main", "next"] +} +``` + +If multiple shareable configurations are defined, they are loaded in order. Local configuration and CLI arguments take precedence over values defined in a shareable configuration. -See [shareable configurations list](../extending/shareable-configurations-list.md). From 7f7214a3dee77e375707c1b9ec5cb4b40174203f Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 22:17:34 +0100 Subject: [PATCH 22/25] feat(docs): update links to shareable configurations in CI and configuration documentation --- src/content/docs/usage/ci-configuration.md | 2 +- src/content/docs/usage/configuration.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/content/docs/usage/ci-configuration.md b/src/content/docs/usage/ci-configuration.md index 4cf8c34..e5a4802 100644 --- a/src/content/docs/usage/ci-configuration.md +++ b/src/content/docs/usage/ci-configuration.md @@ -50,7 +50,7 @@ For GitHub releases, see [@semantic-release/github authentication and permission ### Authentication for plugins -Most **semantic-release** [plugins](/usage/plugins) require setting up authentication in order to publish to a package manager registry. The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) and [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugins require the following environment variables: +Most **semantic-release** [plugins](/foundation/plugins) require setting up authentication in order to publish to a package manager registry. The default [@semantic-release/npm](https://github.com/semantic-release/npm#environment-variables) and [@semantic-release/github](https://github.com/semantic-release/github#environment-variables) plugins require the following environment variables: | Variable | Description | | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/src/content/docs/usage/configuration.md b/src/content/docs/usage/configuration.md index 7fb30b5..0a4bd6a 100644 --- a/src/content/docs/usage/configuration.md +++ b/src/content/docs/usage/configuration.md @@ -10,13 +10,13 @@ Configure semantic-release options, plugins, and release branches via config fil - Plugins [declaration](#plugins) and options - Run mode ([debug](#debug), [dry run](#dryrun) and [local (no CI)](#ci)) -All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](/usage/shareable-configurations). +All of these options can be configured through config file, CLI arguments or by extending a [shareable configuration](/foundation/shareable-configurations). Additionally, metadata of Git tags generated by **semantic-release** can be customized via standard [Git environment variables](#git-environment-variables). ## Configuration file -**semantic-release**’s [options](#options), mode and [plugins](/usage/plugins) can be set via either: +**semantic-release**’s [options](#options), mode and [plugins](/foundation/plugins) can be set via either: - A `.releaserc` file, written in YAML or JSON, with optional extensions: `.yaml`/`.yml`/`.json`/`.js`/`.ts`/`.cjs`/`.mjs` - A `release.config.(js|ts|cjs|mjs)` file that exports an object @@ -83,14 +83,14 @@ $ semantic-release --branches next ## Options -The following are **semantic-release** options you can set in the [configuration file](#configuration-file), pass as [CLI arguments](#cli-arguments), or define in a [shareable configuration](/usage/shareable-configurations). +The following are **semantic-release** options you can set in the [configuration file](#configuration-file), pass as [CLI arguments](#cli-arguments), or define in a [shareable configuration](/foundation/shareable-configurations). ### `extends` **type**: `Array`, `String`\ **CLI arguments**: `-e`, `--extends` -List of modules or file paths containing a [shareable configuration](/usage/shareable-configurations). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration. +List of modules or file paths containing a [shareable configuration](/foundation/shareable-configurations). If multiple shareable configurations are set, they will be imported in the order defined with each configuration option taking precedence over the options defined in a previous shareable configuration. :::note Options defined via CLI arguments or in the configuration file will take precedence over the ones defined in any shareable configuration. From a204afd07b0f362a6c2b901ef31b40d5cd7e9af7 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 22:26:23 +0100 Subject: [PATCH 23/25] feat(docs): add additional context and links for plugins and shareable configurations --- src/content/docs/foundation/plugins.md | 4 +++- src/content/docs/foundation/shareable-configurations.md | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/src/content/docs/foundation/plugins.md b/src/content/docs/foundation/plugins.md index e2fcb4e..c997a32 100644 --- a/src/content/docs/foundation/plugins.md +++ b/src/content/docs/foundation/plugins.md @@ -43,7 +43,7 @@ These four plugins are already part of **semantic-release** and are listed in or ### Additional plugins -[Additional plugins](/extending/plugins-list) should be provided to `npx` with `--package` when running `semantic-release`: +Additional plugins should be provided to `npx` with `--package` when running `semantic-release`: ```bash $ npx \ @@ -53,6 +53,8 @@ $ npx \ semantic-release ``` +See the [official and community plugins list](/extending/plugins-list) for packages that extend **semantic-release** beyond the default set. + ## Plugins declaration and execution order If you need to customize the default plugin set or execution order, configure the [`plugins` option](/usage/configuration/#plugins) by listing plugins by npm module name. diff --git a/src/content/docs/foundation/shareable-configurations.md b/src/content/docs/foundation/shareable-configurations.md index 0b2e146..5eda88c 100644 --- a/src/content/docs/foundation/shareable-configurations.md +++ b/src/content/docs/foundation/shareable-configurations.md @@ -31,3 +31,7 @@ For example, a project can extend a shared base config and still override its ow If multiple shareable configurations are defined, they are loaded in order. Local configuration and CLI arguments take precedence over values defined in a shareable configuration. +## Shareable Configurations list + +See the [shareable configurations list](/extending/shareable-configurations-list) for official and community-maintained packages you can extend. + From a4a62ae5513135928eec8b06b6a9cfa7e30ac840 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 16 May 2026 22:31:52 +0100 Subject: [PATCH 24/25] feat: add links for plugin and shareable configuration development --- src/content/docs/foundation/plugins.md | 2 ++ src/content/docs/foundation/shareable-configurations.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/src/content/docs/foundation/plugins.md b/src/content/docs/foundation/plugins.md index c997a32..bfa1173 100644 --- a/src/content/docs/foundation/plugins.md +++ b/src/content/docs/foundation/plugins.md @@ -55,6 +55,8 @@ $ npx \ See the [official and community plugins list](/extending/plugins-list) for packages that extend **semantic-release** beyond the default set. +If you want to build your own plugin, see [Plugin development](/developer-guide/plugin/). + ## Plugins declaration and execution order If you need to customize the default plugin set or execution order, configure the [`plugins` option](/usage/configuration/#plugins) by listing plugins by npm module name. diff --git a/src/content/docs/foundation/shareable-configurations.md b/src/content/docs/foundation/shareable-configurations.md index 5eda88c..877ee12 100644 --- a/src/content/docs/foundation/shareable-configurations.md +++ b/src/content/docs/foundation/shareable-configurations.md @@ -35,3 +35,5 @@ If multiple shareable configurations are defined, they are loaded in order. Loca See the [shareable configurations list](/extending/shareable-configurations-list) for official and community-maintained packages you can extend. +If you want to build your own shareable configuration, see [Shareable configuration development](/developer-guide/shareable-configuration/). + From 528a483596d3eb54a14877c1fab4400107a6cce7 Mon Sep 17 00:00:00 2001 From: babblebey Date: Sat, 23 May 2026 16:17:55 +0100 Subject: [PATCH 25/25] feat: update Trunk-Based Development link for clarity --- src/content/docs/foundation/supported-branching.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/foundation/supported-branching.md b/src/content/docs/foundation/supported-branching.md index e8194e7..397ebcb 100644 --- a/src/content/docs/foundation/supported-branching.md +++ b/src/content/docs/foundation/supported-branching.md @@ -14,9 +14,8 @@ These models align with the delivery and release assumptions built into **semant ### Trunk-Based Development -- [Trunk-Based Development](https://trunkbaseddevelopment.com/) +- [Trunk-Based Development: Release from Trunk](https://trunkbaseddevelopment.com/release-from-trunk/) - [MinimumCD: Trunk-Based Development](https://minimumcd.org/minimumcd/tbd/) -- [Release from Trunk](https://trunkbaseddevelopment.com/release-from-trunk/) #### Committing Straight to Trunk