Skip to content

Commit 4d01082

Browse files
committed
Link 0ver + blog posts on semver limitations
1 parent e99d27d commit 4d01082

File tree

1 file changed

+22
-5
lines changed

1 file changed

+22
-5
lines changed

source/discussions/versioning.rst

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ semantic versioning and calendar versioning.
6767
Semantic versioning
6868
-------------------
6969

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,
7171
*major.minor.maintenance*, where the project author increments:
7272

7373
- *major* when they make incompatible API changes,
@@ -79,7 +79,8 @@ versioning. However, most projects, especially larger ones, do not strictly
7979
adhere to semantic versioning, since many changes are technically breaking
8080
changes but affect only a small fraction of users. Such projects tend to
8181
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]_.
8384

8485
For those projects that do use strict semantic versioning, this approach allows
8586
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
108109
with a regular time based release cadence and a deprecation process that
109110
provides warnings for a number of releases prior to removal of a feature.
110111

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.
114115

115116
Calendar version numbers typically take the form *year.month* (for example,
116117
23.12 for December 2023).
@@ -154,6 +155,22 @@ since the latest release, setuptools-scm generates a version like
154155
"0.5.dev1+gd00980f.d20231217".
155156

156157

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
157170
.. _calver: https://calver.org
158171
.. _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/
159176
.. _setuptools-scm: https://setuptools-scm.readthedocs.io

0 commit comments

Comments
 (0)