Deciding whether a change is a minor or a patch is a small recurring argument that consumes real time and produces no value. Semantic release removes it by deriving the version from what the commits say: a commit marked as a breaking change bumps the major version, a feature bumps the minor, a fix bumps the patch. No meeting required.
The tradeoff is that a convention nobody follows produces versions nobody trusts.
What changed in 2026
- Commit conventions became widespread. Structured commit message formats moved from a niche practice to a common default in new projects.
- Monorepo release tooling matured. Handling independently versioned packages in one repository, with correct dependency bumps between them, became well supported.
- Publish gating became standard advice. Separating version calculation from the decision to publish addressed the main objection to full automation.
- Provenance attestation joined publishing. Signed build provenance attached at publish time became a normal part of release pipelines.
How the mapping works
| Commit type |
Version effect |
Appears in changelog |
| Fix |
Patch bump |
Yes, under fixes |
| Feature |
Minor bump |
Yes, under features |
| Breaking change marker |
Major bump |
Yes, prominently |
| Performance improvement |
Patch, usually |
Yes |
| Documentation |
None |
Optionally |
| Refactor with no behaviour change |
None |
Usually not |
| Test or build changes |
None |
No |
The changelog is the underrated output. Generating release notes automatically from structured commits means the changelog is always current, always complete, and requires no separate writing step. Teams that dislike automated versioning frequently keep the tooling purely for this.
The breaking change marker deserves emphasis, because it is where the convention most often fails. A developer who does not mark a breaking change ships it as a minor version, and consumers upgrade automatically into a broken state. That is worse than manual versioning, where at least someone thought about it.
Making it work
Enforce the convention mechanically. A commit message linter in a pre-commit hook or CI check is what turns a convention into a guarantee. Relying on people remembering produces inconsistent history and untrustworthy versions.
Squash merge with a curated message. Pull request commits are frequently messy. Squashing with a single conventional message, written deliberately at merge time, gives clean history and puts the version decision at the moment someone is reviewing the change.
Separate versioning from publishing. Calculate the version and prepare the release automatically; gate the actual publish behind whatever approval your context needs. This preserves the benefit while acknowledging that publishing is sometimes a business decision. It also fits naturally with the rollout patterns in zero-downtime deployment.
Handle monorepos deliberately. Independently versioned packages need tooling that understands which packages a change affects and bumps dependents correctly. The alternative — versioning everything together — is simpler and produces version churn in packages that did not change. Changesets versioning covers the explicit-declaration alternative.
Common mistakes
- No enforcement of the convention. Inconsistent history, untrustworthy versions.
- Unmarked breaking changes. Ships as minor, breaks consumers on auto-update.
- Fully automated publishing for a product with a release cadence. Version automatically, publish deliberately.
- Retrofitting onto messy history. Start from a clean point rather than backfilling.
- Versioning all monorepo packages together. Churn in unchanged packages.
FAQ
Does it work with monorepos?
With tooling designed for it, yes. Independent package versioning needs a tool that tracks which packages each change affects.
What if we release on a schedule rather than per merge?
Calculate versions automatically and batch the publish. The version arithmetic is still useful even if release timing is not automated.
How do we handle a mistaken release?
Publish a new version rather than unpublishing. Most registries discourage or prohibit unpublishing precisely because consumers depend on immutability.
Is the commit convention worth it on its own?
Many teams find the generated changelog alone justifies it, independent of automated versioning.
Where to go next
For the alternative approach, read changesets versioning. For commit and review practice, pull request review culture, and for deployment, zero-downtime deployment.