@@ -67,7 +67,7 @@ semantic versioning and calendar versioning.
6767Semantic 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
7979adhere to semantic versioning, since many changes are technically breaking
8080changes but affect only a small fraction of users. Such projects tend to
8181increment 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
8485For those projects that do use strict semantic versioning, this approach allows
8586users 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
108109with a regular time based release cadence and a deprecation process that
109110provides 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
115116Calendar version numbers typically take the form *year.month * (for example,
11611723.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