Semantic Versioning
Semantic Versioning, often shortened to SemVer, is a specification for version numbers of the form MAJOR.MINOR.PATCH, in which each part communicates what kind of change a release contains. Its purpose is to let users tell from the number alone whether upgrading can break them.
The three rules
| Increment | When, per the specification | What users can expect |
|---|---|---|
| MAJOR (2.0.0 → 3.0.0) | “when you make incompatible API changes” | Something they rely on may break |
| MINOR (2.3.0 → 2.4.0) | “when you add functionality in a backward compatible manner” | New capabilities; existing use keeps working |
| PATCH (2.3.1 → 2.3.2) | “when you make backward compatible bug fixes” | Corrections; existing use keeps working |
A few further rules keep the scheme honest. Once a version has been released, its contents must not be modified; any change is a new version. Major version zero (0.y.z) is for initial development, where anything may change and the public API should not be considered stable; version 1.0.0 defines the public API.
The rule that makes the others work
Before any of this, the specification requires that software using it “MUST declare a public API,” and that the declaration “SHOULD be precise and comprehensive.” That requirement carries the weight. “Incompatible” only has meaning relative to a stated interface; without one, every change is arguably breaking and none is provably so. The version number is a summary of a promise, and the promise has to exist first.
Applying it to data
Data models, tables, and datasets can use the same idea, provided the public interface is declared. For a published table that interface is more than column names and types: it includes the grain (what one row represents) and the definitions of its measures. With that declared:
- removing or renaming a column, changing a type, or changing the grain is MAJOR;
- adding a nullable column is usually MINOR;
- fixing a load bug so values match the stated definition is PATCH.
The trap is the last category. Changing what a measure means — deciding that “revenue” now excludes cancelled orders — can pass every structural check and be recorded as a bug fix, yet it breaks every consumer who compares this month to last. If the definition is part of the declared interface, that change is MAJOR, however small the code change.
A version number also does not migrate anyone. Retiring the old major version still needs deprecation with a date. How versioning, compatibility, and meaning changes fit together is worked through in Changing a Data Model Without Breaking the People Using It, and structural compatibility directions are covered in schema evolution and compatibility.
References: Semantic Versioning 2.0.0.
Discover more from Insightful Data Lab
Subscribe to get the latest posts sent to your email.