This is a variant of SemVer which mostly meets all its rules, except for releases prior to 0.2.0, where we bend them slightly.
It is my intention to use this versioning system for all open source software I develop from 1 January 2023 onwards. Existing open source projects I manage will adopt this scheme from their next release onwards. (Type::Tiny already somewhat does.)
-
Like with SemVer, versions have three parts: MAJOR, MINOR, and PATCH.
-
Adopting a common pattern that many projects use (including Linux), versions with an odd-numbered MINOR part are considered unstable.
-
During unstable development periods (i.e. odd-numbered minor versions), you can add new features, break backwards compatibility, etc as much as you like. This would violate SemVer, except…
-
All unstable development releases must have a pre-release identifier such as
-devapplied to them. SemVer explicitly states:“A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.”
-
As an exception, 0.1.x releases should not be assumed to have a stable API at all, and thus do not need
-devsuffixes. -
At the end of an unstable development cycle, for example, 0.5.x versions, the developers should judge whether to release the next stable release as 0.6.0 or 1.0.0 based on how much it differs with the 0.4.x versions, as if the 0.5.x versions never happened.
Example
-
The first release of a project would be 0.1.0. This would be unstable.
-
The next release of a project would be 0.1.1. This would also be unstable and could include breaking changes.
-
Perhaps now there has been sufficient experimentation, so the next version would be 0.2.0 and would be considered stable.
-
Version 0.2.1 might include bug fixes but no breaking changes.
-
New features are desired, so 0.3.0-dev is released with a first draft of these features.
-
0.3.1-dev, 0.3.2-dev, and 0.3.3-dev follow swiftly after.
-
The new features are judged to be stable enough. The developers must then decide whether the next release will retain compatibility with 0.2.x (and thus be called 0.4.0) or break compatibility (and thus warrant a bump to 1.0.0).
Decimal Variation
Although dotted version numbers like 1.2.3 are supported by most of the Perl toolchain, simple decimals with a single dot are more commonly used. So an interpretation of the above using simple decimals is desired. The MAJOR part of the version number translates to units, MINOR to thousandths, and PATCH to millionths. So version 1.2.3 becomes 1.002003.
In Perl it is also common to use an underscore in the version number to indicate an unstable release. For example version 1.3.2 might be 1.003_002.
