@@ -67,7 +67,7 @@ semantic versioning and calendar versioning.
67
67
Semantic versioning
68
68
-------------------
69
69
70
- The idea of *semantic versioning * is to use 3-part version numbers,
70
+ The idea of *semantic versioning * (or SemVer) is to use 3-part version numbers,
71
71
*major.minor.maintenance *, where the project author increments:
72
72
73
73
- *major * when they make incompatible API changes,
@@ -79,7 +79,8 @@ versioning. However, most projects, especially larger ones, do not strictly
79
79
adhere to semantic versioning, since many changes are technically breaking
80
80
changes but affect only a small fraction of users. Such projects tend to
81
81
increment the major number when the incompatibility is high, or to signal a
82
- shift in the project, rather than for any tiny incompatibility,
82
+ shift in the project, rather than for any tiny incompatibility
83
+ [#semver-strictness ]_.
83
84
84
85
For those projects that do use strict semantic versioning, this approach allows
85
86
users to make use of :ref: `compatible release version specifiers
@@ -108,9 +109,9 @@ Semantic versioning is not a suitable choice for all projects, such as those
108
109
with a regular time based release cadence and a deprecation process that
109
110
provides warnings for a number of releases prior to removal of a feature.
110
111
111
- A key advantage of date-based versioning, or `calendar versioning <calver _>`_,
112
- is that it is straightforward to tell how old the base feature set of a
113
- particular release is given just the version number.
112
+ A key advantage of date-based versioning, or `calendar versioning <calver _>`_
113
+ (CalVer), is that it is straightforward to tell how old the base feature set of
114
+ a particular release is given just the version number.
114
115
115
116
Calendar version numbers typically take the form *year.month * (for example,
116
117
23.12 for December 2023).
@@ -154,6 +155,22 @@ since the latest release, setuptools-scm generates a version like
154
155
"0.5.dev1+gd00980f.d20231217".
155
156
156
157
158
+ --------------------------------------------------------------------------------
159
+
160
+
161
+ .. [#semver-strictness ] For some personal viewpoints on this issue, see these
162
+ blog posts: `by Hynek Schlawak <semver-hynek-schlawack _>`_, `by Donald Stufft
163
+ <semver-donald-stufft_> `_, `by Bernát Gábor <semver-bernat-gabor _>`_, `by
164
+ Brett Cannon <semver-brett-cannon_> `_. For a humoristic take, read about
165
+ ZeroVer _.
166
+
167
+
168
+
169
+ .. _zerover : https://0ver.org
157
170
.. _calver : https://calver.org
158
171
.. _semver : https://semver.org
172
+ .. _semver-bernat-gabor : https://bernat.tech/posts/version-numbers/
173
+ .. _semver-brett-cannon : https://snarky.ca/why-i-dont-like-semver/
174
+ .. _semver-donald-stufft : https://caremad.io/posts/2016/02/versioning-software/
175
+ .. _semver-hynek-schlawack : https://hynek.me/articles/semver-will-not-save-you/
159
176
.. _setuptools-scm : https://setuptools-scm.readthedocs.io
0 commit comments