Dependency versioning strategy
Design a dependency versioning strategy
SemVer
MAJOR.MINOR.PATCH — and the contract is what matters, not the digits:
| Increment | Meaning |
|---|---|
| MAJOR | Breaking change. Consumers must act. |
| MINOR | Backward-compatible functionality added. |
| PATCH | Backward-compatible fix. |
Pre-release identifiers (1.4.0-beta.2) sort before the release they precede, which is exactly why @prerelease views exist.
The value of SemVer is that a consumer can express intent — "any compatible update" — and have the range mean something. That only holds if publishers honour it; a MAJOR change shipped as a PATCH is worse than no scheme, because it defeats a guarantee consumers relied on.
CalVer
YYYY.MM.DD or YY.MM.MICRO — versions encode when, not what changed.
Choose CalVer when time is the meaningful axis: distributions, datasets, and products whose consumers care about currency and where breaking changes are communicated out-of-band. Choose SemVer for libraries, where the consumer's real question is "can I take this upgrade safely?" — a question a date cannot answer.
Pinning
Exact pins give reproducibility and stale dependencies. Ranges give currency and non-determinism. The usual resolution is a range plus a committed lock file: intent stays expressive, resolution stays reproducible, and updating is a deliberate, reviewable commit.
Primary sources