Skip to content

Commit 691e70e

Browse files
theoephraimtheoephraim
committed
docs: add comparisons page
1 parent 408654d commit 691e70e

1 file changed

Lines changed: 157 additions & 0 deletions

File tree

‎docs/comparisons.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Comparisons with Other Tools
2+
3+
There are several great tools in the release management space, each with different design philosophies and trade-offs. This page gives an honest comparison of bumpy with the most popular alternatives, focusing on where each tool shines and where it falls short.
4+
5+
> Bumpy's core design choice is **explicit bump files per PR** — small markdown files that declare which packages are changing, at what level, and with a human-written description. This gives precise per-package control and produces consumer-facing changelogs, but requires slightly more work per PR than label- or commit-based approaches. Many of the differences below stem from this choice.
6+
7+
---
8+
9+
## Changesets
10+
11+
[Changesets](https://github.com/changesets/changesets) is the most direct comparison — bumpy uses the same bump-file-per-PR model and is designed as a successor to it. Changesets is mature, widely adopted, and battle-tested across many large monorepos.
12+
13+
**Where changesets shines:**
14+
15+
- Proven at scale with years of production use across the ecosystem
16+
- Large community with extensive documentation and third-party integrations
17+
- Stable, well-understood behavior
18+
19+
**Where bumpy differs:**
20+
21+
- **Dependency propagation** — changesets hardcodes aggressive peer dep behavior (a minor bump can trigger major bumps on dependents). Bumpy uses a [configurable three-phase algorithm](./version-propagation.md) with sensible defaults.
22+
- **Workspace protocols** — changesets uses `npm publish` even in pnpm/yarn workspaces, so `workspace:^` and `catalog:` protocols may not be resolved correctly. Bumpy resolves these before publishing.
23+
- **Custom publish commands** — changesets is locked to `npm publish`. Bumpy supports per-package custom commands for VSCode extensions, Docker images, JSR, etc.
24+
- **CI setup** — changesets requires a [GitHub App](https://github.com/apps/changeset-bot) and a [separate GitHub Action](https://github.com/changesets/action). Bumpy uses two CLI commands (`bumpy ci check` + `bumpy ci release`) that run directly in your workflows.
25+
- **Non-interactive CLI** — `bumpy add` works fully non-interactively, which is important for CI/CD and AI-assisted workflows.
26+
27+
For a detailed breakdown with links to specific changesets issues, see [Differences from Changesets](./differences-from-changesets.md).
28+
29+
---
30+
31+
## semantic-release
32+
33+
[semantic-release](https://github.com/semantic-release/semantic-release) is the most popular fully-automated release tool. It analyzes commit messages (typically [Angular convention](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-format.md)) to determine version bumps, generate changelogs, and publish — all without human intervention after merge.
34+
35+
**Where semantic-release shines:**
36+
37+
- Truly zero-touch releases — no manual step between merge and publish
38+
- Rich plugin ecosystem for different registries, CI providers, and changelog formats
39+
- Enforces consistent commit discipline across teams
40+
- Well-suited for single-package repos with a linear commit history
41+
42+
**Where bumpy differs:**
43+
44+
- **Monorepo support** — semantic-release was designed for single packages. Monorepo support exists via plugins like [multi-semantic-release](https://github.com/dhoulb/multi-semantic-release), but it's not first-class and can be fragile.
45+
- **Per-PR granularity** — with semantic-release, a squash-merged PR produces a single commit, so the version bump is determined by the commit message of the squash. If a PR touches multiple packages at different levels, this is hard to express. Bump files let you specify different bump levels for different packages in a single PR.
46+
- **Changelog quality** — semantic-release changelogs are derived from commit messages, which tend to be written for developers. Bump files let you write descriptions aimed at package consumers.
47+
- **Review before release** — bumpy's release PR gives maintainers a chance to review the full release plan before it goes out. semantic-release publishes immediately on merge with no review step (by design — this is a feature for some teams).
48+
- **Commit convention requirement** — semantic-release requires strict commit message formatting. Bumpy works with any commit style (though `bumpy generate` can optionally derive bump files from conventional commits).
49+
50+
**When to choose semantic-release:** You have a single-package repo (or a small set of independent packages), your team is disciplined about commit conventions, and you want fully hands-off publishing with no release PR step.
51+
52+
---
53+
54+
## release-please
55+
56+
[release-please](https://github.com/googleapis/release-please) is Google's release automation tool. Like semantic-release, it uses conventional commits — but instead of publishing immediately, it maintains a release PR that accumulates changes. Merging the PR triggers tagging and GitHub release creation.
57+
58+
**Where release-please shines:**
59+
60+
- Broad language support — 18+ ecosystems (Node, Python, Java, Go, Rust, Ruby, PHP, etc.) with language-specific version file updates
61+
- Release PR model gives maintainers a review step before release (similar to bumpy)
62+
- Squash-merge friendly with good linear history support
63+
- Manual version overrides via `Release-As: x.y.z` commit footer
64+
- Backed by Google with active maintenance
65+
66+
**Where bumpy differs:**
67+
68+
- **Commit convention requirement** — release-please requires conventional commits for version determination. Bumpy doesn't require any commit convention.
69+
- **Per-package control in PRs** — release-please determines bump levels from commits, so a single PR can't easily express "minor for package A, patch for package B." Bump files make this explicit.
70+
- **Publishing** — release-please deliberately does not handle publishing; you need separate CI steps for that. Bumpy handles versioning _and_ publishing (with workspace protocol resolution, topological ordering, etc.).
71+
- **JS-specific features** — bumpy handles `workspace:` and `catalog:` protocol resolution, npm OIDC/provenance, staged publishing, and per-package publish commands. Release-please is language-agnostic but doesn't go as deep on npm-specific concerns.
72+
- **Dependency propagation** — release-please doesn't model inter-package dependency relationships. In a JS monorepo where bumping `core` should cascade to `plugin`, you'd need to handle this yourself.
73+
74+
**When to choose release-please:** You have a polyglot monorepo (Go + Python + Rust, etc.), your team already uses conventional commits, and you handle publishing separately. Its breadth of language support is unmatched.
75+
76+
---
77+
78+
## release-it
79+
80+
[release-it](https://github.com/release-it/release-it) is a flexible, interactive CLI tool for managing releases. It handles version bumping, git tagging, GitHub/GitLab releases, and npm publishing — typically run locally by a developer rather than fully automated in CI.
81+
82+
**Where release-it shines:**
83+
84+
- Interactive mode with confirmation prompts gives developers full control over each release step
85+
- Works as a generic release tool beyond just npm — supports any project with git tags
86+
- Plugin system for conventional changelogs, custom version sources, and monorepo support
87+
- Pre-release version support (alpha, beta, rc) out of the box
88+
- Lightweight and flexible — doesn't impose a specific workflow
89+
90+
**Where bumpy differs:**
91+
92+
- **PR-based workflow** — bumpy is designed around accumulating changes across multiple PRs via bump files, then releasing them together. release-it is typically a point-in-time "release what's on main now" tool.
93+
- **Monorepo support** — release-it has monorepo recipes and plugins, but it's primarily designed for single-package repos. Bumpy's dependency propagation, per-package config, and workspace protocol handling are built for complex monorepos.
94+
- **Changelog source** — release-it generates changelogs from git history. Bumpy uses human-written descriptions from bump files.
95+
- **CI-first design** — bumpy is designed to run unattended in CI with its release PR workflow. release-it's strength is its interactive local flow (though it supports CI mode too).
96+
97+
**When to choose release-it:** You prefer running releases locally with interactive confirmation, have a single-package repo, or need a lightweight tool that doesn't impose a PR-based workflow.
98+
99+
---
100+
101+
## uppt
102+
103+
[uppt](https://github.com/danielroe/uppt) is a composite GitHub Action by [Daniel Roe](https://github.com/danielroe) focused on secure npm publishing. It uses conventional commits to create release PRs, then packs and publishes via OIDC trusted publishing with npm staged releases.
104+
105+
**Where uppt shines:**
106+
107+
- Security-first design — OIDC trusted publishing with no stored tokens, immutable tarball artifacts, and staged publishing requiring manual npm approval
108+
- Clean separation of concerns — four modular sub-actions (PR, release, pack, publish) with minimal permissions per step
109+
- Fork protection guards against accidental releases from merged fork PRs
110+
- Opinionated and simple — does one thing well with minimal configuration
111+
112+
**Where bumpy differs:**
113+
114+
- **Versioning model** — uppt uses conventional commits to determine versions. Bumpy uses explicit bump files, giving per-package control independent of commit style.
115+
- **Monorepo support** — uppt is designed for single-package repos. Bumpy handles monorepos with dependency propagation, per-package config, and workspace protocol resolution.
116+
- **Publishing flexibility** — uppt targets npm exclusively with staged publishing. Bumpy supports npm (with optional OIDC/provenance/staged), plus custom publish commands for other targets.
117+
- **Scope** — uppt is a GitHub Action, so it's tied to GitHub Actions as a CI provider. Bumpy is a CLI that can run anywhere.
118+
119+
**When to choose uppt:** You have a single npm package, want maximum supply-chain security with staged publishing, and prefer a GitHub Actions-native solution with minimal setup.
120+
121+
---
122+
123+
## release-plan
124+
125+
[release-plan](https://github.com/release-plan/release-plan) uses PR labels to drive versioning. Merged PRs are categorized by label (`breaking`, `enhancement`, `bug`, etc.), and the tool creates a release PR with computed version bumps and changelogs derived from PR titles.
126+
127+
**Where release-plan shines:**
128+
129+
- Minimal per-PR overhead — contributors just add a label, no files to create
130+
- Changelog entries come from PR titles, which teams are already writing
131+
- Simple mental model — one label, one PR, one version impact
132+
- Zero local credentials needed — everything runs in CI
133+
- Good support for pre-release workflows via `semverIncrementAs` and `publishTag` config
134+
135+
**Where bumpy differs:**
136+
137+
- **Multi-package PRs** — release-plan assigns one label per PR, so all packages in that PR get the same bump level. Bump files can specify different levels for different packages.
138+
- **Changelog quality** — PR titles are often written for developer context ("Fix flaky test in auth module") rather than consumer context ("Fixed authentication timeout on slow connections"). Bump file descriptions are purpose-written for changelogs.
139+
- **Monorepo depth** — release-plan supports monorepos but all packages share the same configuration. Bumpy offers per-package config, dependency propagation rules, and include/exclude controls.
140+
- **Per-package configuration** — release-plan applies uniform config across all packages. Bumpy supports per-package publish commands, access levels, and propagation rules.
141+
- **Publish targets** — release-plan publishes to npm. Bumpy supports npm plus custom publish commands for other targets.
142+
143+
**When to choose release-plan:** You want the lowest possible friction per PR, your PRs typically affect one package each, and PR titles naturally serve as good changelog entries. Its simplicity is a genuine advantage for smaller projects.
144+
145+
---
146+
147+
## Quick Reference
148+
149+
| | Versioning source | Monorepo | Publish | Release PR | Commit convention required |
150+
| -------------------- | ------------------------ | -------------- | -------------------- | ---------------- | -------------------------- |
151+
| **bumpy** | Bump files (per PR) | First-class | npm + custom targets | Yes | No |
152+
| **changesets** | Changeset files (per PR) | First-class | npm only | Yes | No |
153+
| **semantic-release** | Commit messages | Via plugins | Via plugins | No (immediate) | Yes |
154+
| **release-please** | Commit messages | Yes (manifest) | No (external) | Yes | Yes |
155+
| **release-it** | Interactive / plugins | Via plugins | npm + git platforms | No (interactive) | Optional |
156+
| **uppt** | Commit messages | No | npm (staged) | Yes | Yes |
157+
| **release-plan** | PR labels | Yes | npm | Yes | No |

0 commit comments

Comments
 (0)