Semantic Versioning

What it is

Semantic Versioning (SemVer) is a versioning scheme of the form MAJOR.MINOR.PATCH, where each segment carries a specific meaning:

• MAJOR — incompatible/breaking API changes
• MINOR — backward-compatible functionality added
• PATCH — backward-compatible bug fixes

Optional pre-release (-alpha.1) and build-metadata (+build.5) suffixes extend the core triplet. The core promise is that consumers can read a version bump and know, without reading a changelog, whether upgrading is safe: a PATCH or MINOR bump should never break existing usage; a MAJOR bump might.

Why we adopted this

• Predictable upgrades. Anyone depending on a w3dev package can set a version range (^1.2.0) and trust that patch/minor releases won't break them — that trust is the entire point of the scheme.
• Pairs with automated tooling. Combined with conventional-commits, commit types map directly to version bumps (fix → patch, feat → minor, breaking change → major), so releases don't require a human to decide the version by hand.
• Universal. It's the default versioning expectation across the npm, Cargo, and most language package ecosystems w3dev repos already depend on — there's no reason to deviate.

w3dev-specific notes

• Version bumps are derived, not chosen. Release tooling computes the bump from Conventional Commit history on main (see conventional-commits) — don't manually pick a version number in a release PR.
• Pre-1.0 packages still apply the rule strictly. 0.y.z is allowed to break on any change per the spec, but within a w3dev 0.x package, treat 0.MINOR bumps as breaking and 0.x.PATCH as fixes — document the exception in the package's own README so consumers aren't surprised.
• Every release gets a changelog entry. Pair each version bump with a matching entry under keep-a-changelog conventions so the why behind a bump is recorded, not just the number.

Links

• Canonical: https://semver.org
• Version: 2.0.0 — https://semver.org/spec/v2.0.0.html