From 0c0cdff458fcbfc6705363ede22719f9ee8b4145 Mon Sep 17 00:00:00 2001 From: Felix Schneider <99918022+trueberryless@users.noreply.github.com> Date: Fri, 26 Jun 2026 09:28:06 +0200 Subject: [PATCH 1/3] docs: update and enhance comparison to other tools --- site/guide/technical-decisions.md | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) diff --git a/site/guide/technical-decisions.md b/site/guide/technical-decisions.md index 00f767806..ddd576e26 100644 --- a/site/guide/technical-decisions.md +++ b/site/guide/technical-decisions.md @@ -33,21 +33,31 @@ All updating of dependencies is done as a patch bump. If you want to indicate a There are two reasons we chose to do this. The first is so the changeset descriptions are editable after creation, and a user can go in and change this as they desire. The second is that it means we are unopinionated about your git workflows, with squashing and modifying commits being completely safe, without fear of breaking a release. -## What distinguishes this from Semantic Release +## What distinguishes this from other versioning tools -If you have been looking at automating versioning previously, you may have come across [semantic release](https://github.com/semantic-release/semantic-release), or its monorepo equivalent [lerna semantic release](https://github.com/atlassian/lerna-semantic-release). It's good to understand how changesets operate differently. +If you have been looking at automating versioning previously, you may have come across [Release Please](https://github.com/googleapis/release-please) or [Semantic Release](https://github.com/semantic-release/semantic-release). It's good to understand how changesets operate differently. -1. Changesets are designed for monorepos first. +1. Changesets are designed for monorepos first. Changesets allow you to group linked packages, define fixed packages, and explicitly declare whether an internal dependency bump should trigger a patch bump on the consuming package. -This means we manage dependencies within the repository, which other tools do not do. +2. We store our change intent in dedicated Markdown files alongside your code, rather than relying on strict git commit message parsing. See the above section on why we write files to disc. -2. We commit our change information to the file system, instead of storing it in git. +3. We use semver for specifying the change. When selecting the kind of change your package is, we do not specify any change types beyond `major`, `minor`, or `patch`. In comparison, [conventional commits](https://github.com/conventional-commits/conventionalcommits.org) specify the type of a commit (bug, feat) that gets converted to an appropriate semver type. This is a design decision on our part to push adding this information into the changeset description itself. -See the above section on why we write files to disc. +### Comparison to Semantic Release -3. We use semver for specifying the change. +[Semantic Release](https://github.com/semantic-release/semantic-release) focuses on publishing bug fixes and new features as soon as possible without release PRs. With the default CI for Semantic Release, conventional commits landing on the specified branch are published immediately. -When selecting the kind of change your package is, we do not specify any change types beyond `major`, `minor`, or `patch`. The semantic release allows you to specify a range of fields (bug-fix, feature) that it converts to an appropriate semver type. This is a design decision on our part to push adding this information into the changeset description itself. +While monorepo equivalents (like [Multi Semantic Release](https://github.com/dhoulb/multi-semantic-release) or [Lerna Semantic Release (unmaintained)](https://github.com/atlassian/lerna-semantic-release)) attempt to adapt it for multi-package repositories, standard Semantic Release is designed for single-package repositories. + +### Comparison to Release Please + +[Release Please](https://github.com/googleapis/release-please) takes a similar approach to semantic release, where conventional commits determine the semver bump. One difference to semantic release - and a similarity to changesets - is the automatic creation of release PRs that need to be merged to trigger a new release. + +However, Release Please does not manage publication of packages or complex branch management. + +While tools like Release Please support monorepos, Changesets deeply integrates with workspace topologies - giving you fine-grained control over how internal dependency bumps (like `peerDependencies`) cascade through linked packages. + +A big advantage of Release Please is its language independence. It supports [15+ strategies](https://github.com/googleapis/release-please#strategy-language-types-supported). There are community-driven ports of changesets for other languages though, like [C#](https://github.com/solarwinds/net-changesets), [Rust](https://github.com/knope-dev/changesets) and [Go](https://github.com/nesymno/changesets). ## The versioning of peer dependencies From fed980c1fd6b0672f55f41249fc747b1a53fb0f3 Mon Sep 17 00:00:00 2001 From: Felix Schneider <99918022+trueberryless@users.noreply.github.com> Date: Thu, 2 Jul 2026 20:50:59 +0200 Subject: [PATCH 2/3] docs: rephrase all sections to objectively compare Changesets to conventional commit-based tools --- site/guide/technical-decisions.md | 26 +++++--------------------- 1 file changed, 5 insertions(+), 21 deletions(-) diff --git a/site/guide/technical-decisions.md b/site/guide/technical-decisions.md index ddd576e26..6616239b1 100644 --- a/site/guide/technical-decisions.md +++ b/site/guide/technical-decisions.md @@ -33,31 +33,15 @@ All updating of dependencies is done as a patch bump. If you want to indicate a There are two reasons we chose to do this. The first is so the changeset descriptions are editable after creation, and a user can go in and change this as they desire. The second is that it means we are unopinionated about your git workflows, with squashing and modifying commits being completely safe, without fear of breaking a release. -## What distinguishes this from other versioning tools +## How Changesets differs from conventional commit-based tools -If you have been looking at automating versioning previously, you may have come across [Release Please](https://github.com/googleapis/release-please) or [Semantic Release](https://github.com/semantic-release/semantic-release). It's good to understand how changesets operate differently. +While many versioning tools rely on conventional commits to determine releases, Changesets was built with a different philosophy, prioritizing monorepo management and flexible workflows over strict commit message parsing. -1. Changesets are designed for monorepos first. Changesets allow you to group linked packages, define fixed packages, and explicitly declare whether an internal dependency bump should trigger a patch bump on the consuming package. +1. Monorepo-first design: Changesets is built to manage complex workspace topologies. It allows you to group linked packages, define fixed packages, and explicitly declare how internal dependency bumps (like `peerDependencies`) cascade through your repository. -2. We store our change intent in dedicated Markdown files alongside your code, rather than relying on strict git commit message parsing. See the above section on why we write files to disc. +2. Intent-based files: Instead of parsing git commit messages, change intent is stored in dedicated Markdown files committed alongside your code. This ensures that release information is preserved regardless of how your git history is squashed or rewritten. -3. We use semver for specifying the change. When selecting the kind of change your package is, we do not specify any change types beyond `major`, `minor`, or `patch`. In comparison, [conventional commits](https://github.com/conventional-commits/conventionalcommits.org) specify the type of a commit (bug, feat) that gets converted to an appropriate semver type. This is a design decision on our part to push adding this information into the changeset description itself. - -### Comparison to Semantic Release - -[Semantic Release](https://github.com/semantic-release/semantic-release) focuses on publishing bug fixes and new features as soon as possible without release PRs. With the default CI for Semantic Release, conventional commits landing on the specified branch are published immediately. - -While monorepo equivalents (like [Multi Semantic Release](https://github.com/dhoulb/multi-semantic-release) or [Lerna Semantic Release (unmaintained)](https://github.com/atlassian/lerna-semantic-release)) attempt to adapt it for multi-package repositories, standard Semantic Release is designed for single-package repositories. - -### Comparison to Release Please - -[Release Please](https://github.com/googleapis/release-please) takes a similar approach to semantic release, where conventional commits determine the semver bump. One difference to semantic release - and a similarity to changesets - is the automatic creation of release PRs that need to be merged to trigger a new release. - -However, Release Please does not manage publication of packages or complex branch management. - -While tools like Release Please support monorepos, Changesets deeply integrates with workspace topologies - giving you fine-grained control over how internal dependency bumps (like `peerDependencies`) cascade through linked packages. - -A big advantage of Release Please is its language independence. It supports [15+ strategies](https://github.com/googleapis/release-please#strategy-language-types-supported). There are community-driven ports of changesets for other languages though, like [C#](https://github.com/solarwinds/net-changesets), [Rust](https://github.com/knope-dev/changesets) and [Go](https://github.com/nesymno/changesets). +3. Direct Semver selection: When creating a changeset, you directly specify a `major`, `minor`, or `patch` bump. Conventional commit-based tools, by comparison, rely on mapping specific commit types (e.g., `feat`, `fix`) to semver increments. We believe this design choice provides more clarity by keeping the documentation and the versioning intent together. ## The versioning of peer dependencies From 58fd545ebb70331bc5cc72796cf5f3d42d0e75eb Mon Sep 17 00:00:00 2001 From: Felix Schneider <99918022+trueberryless@users.noreply.github.com> Date: Fri, 3 Jul 2026 06:45:04 +0200 Subject: [PATCH 3/3] Update site/guide/technical-decisions.md Co-authored-by: Bjorn Lu --- site/guide/technical-decisions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/guide/technical-decisions.md b/site/guide/technical-decisions.md index 6616239b1..ec91f8b8d 100644 --- a/site/guide/technical-decisions.md +++ b/site/guide/technical-decisions.md @@ -37,7 +37,7 @@ There are two reasons we chose to do this. The first is so the changeset descrip While many versioning tools rely on conventional commits to determine releases, Changesets was built with a different philosophy, prioritizing monorepo management and flexible workflows over strict commit message parsing. -1. Monorepo-first design: Changesets is built to manage complex workspace topologies. It allows you to group linked packages, define fixed packages, and explicitly declare how internal dependency bumps (like `peerDependencies`) cascade through your repository. +1. Monorepo-first design: Changesets is built to manage complex workspace topologies. It allows you to group linked packages, define fixed packages, and explicitly declare how internal dependency bumps cascade through your repository. 2. Intent-based files: Instead of parsing git commit messages, change intent is stored in dedicated Markdown files committed alongside your code. This ensures that release information is preserved regardless of how your git history is squashed or rewritten.