Semantic versioning
Core version
Semantic versioning (a.k.a. semver) says that when you see versions like:
3.1.0
to read them like:
major.minor.patch
where
- you increase major version to signal breaking changes
- such as API changes
- you increase minor version to indicate added features
- that do not change how to interact with existing code
- you increase patch version to indicate bugfixes and other patches
- that do not change how to interact with existing code
Practically
What consists of breaking change is still up to some interpretation, and may vary with how your language works (from syntax to runtime).
For example, renaming a keyword argument isn't even a change in the function's behaviour,
but in many cases is a breaking API change - in that any calls by the old keyword will now fail,
...but not everyone will take that to mean they should increase major,
because they associate major with "a large feature change that also happens to be breaking",
minor for "we're working on serous things".
Further info
The three numbers are the core version.
On top of that, you can add prerelease label and/or build info (sometimes called 'metadata'), e.g.
1.2.1-beta3+20190214
major.minor.patch-prerelease major.minor.patch+build major.minor.patch-prerelease+build
Semver sorting
See https://semver.org/#spec-item-11
- major, minor, and patch
- must be split, and sorted as separate integers
- meaning that lexograpical sorting is incorrect and treating the dot as decimal separator them as numbers is incorrect
- which are two ways of saying that in semver, e.g. 3.12 is larger than 3.4
- labels
- are sorted lexograpically
- things with a label come before those without
- +build metadata is irrelevant to sorting (but could still be sorted on in actual lists)