2 min read
Versioning
Every project needs a clear versioning strategy. Without one, consumers of your code — whether they are other developers, package managers, or end users — have no way to understand the significance of a change or whether it will break their existing setup.
Semantic Versioning (SemVer)
Semantic Versioning is the most widely adopted versioning system in software development. It communicates the nature and risk of each release through a simple three-number format:
MAJOR.MINOR.PATCH
For example: v2.1.3
Major — v2.0.0
A major version bump signals a breaking change. Something in the public interface has changed in a way that requires consumers to update their code. When you see a major version increase, read the migration notes before upgrading.
Minor — v2.1.0
A minor version bump introduces new functionality that is backwards compatible with the previous minor version. Existing code will continue to work without modification; you simply have access to new features if you want them.
Patch — v2.1.3
A patch version bump delivers bug fixes that are backwards compatible. No new features, no interface changes — just corrections to existing behaviour.
Pre-Release Versions
SemVer also supports pre-release identifiers for versions that are not yet stable. Append a hyphen and a label after the patch number:
v2.1.0-alpha.1 v2.1.0-beta.2 v2.1.0-rc.1
These signals tell consumers that the release is not yet production-ready and that the interface may still change.
When to Bump
- You fix a bug with no interface change: bump the patch number.
- You add a new feature without breaking anything: bump the minor number and reset the patch to zero.
- You change or remove part of the public interface: bump the major number and reset minor and patch to zero.
Following this discipline consistently means that your version numbers carry real information — consumers can decide whether to upgrade based on the version alone.