From 3820102558ba6b26c25f3348608a03c3b12c66d4 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sun, 17 Dec 2023 13:10:26 +0100 Subject: [PATCH 1/8] Create a discussion on versioning Move content on versioning schemes from distributing-packages-using-setuptools.rst to a new discussion on versioning, and update it. --- source/discussions/index.rst | 1 + source/discussions/versioning.rst | 139 ++++++++++++++++++ ...distributing-packages-using-setuptools.rst | 119 --------------- source/specifications/version-specifiers.rst | 2 + 4 files changed, 142 insertions(+), 119 deletions(-) create mode 100644 source/discussions/versioning.rst diff --git a/source/discussions/index.rst b/source/discussions/index.rst index b378ed810..4a14fbfba 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -8,6 +8,7 @@ specific topic. If you're just trying to get stuff done, see .. toctree:: :maxdepth: 1 + versioning deploying-python-applications pip-vs-easy-install install-requires-vs-requirements diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst new file mode 100644 index 000000000..c901ff345 --- /dev/null +++ b/source/discussions/versioning.rst @@ -0,0 +1,139 @@ +.. _versioning: +.. _`Choosing a versioning scheme`: + +========== +Versioning +========== + +This discussion covers all aspects of versioning Python packages. + + +Valid version numbers +===================== + +Different Python projects may use different versioning schemes based on the +needs of that particular project, but in order to be compatible with tools like +:ref:`pip`, all of them are required to comply with a flexible format for +version identifiers, for which the authoritative reference is the +:ref:`specification of version specifiers `. Here are some +examples of version numbers: + +.. code-block:: text + + 1.2.0.dev1 # Development release + 1.2.0a1 # Alpha Release + 1.2.0b1 # Beta Release + 1.2.0rc1 # Release Candidate + 1.2.0 # Final Release + 1.2.0.post1 # Post Release + 15.10 # Date based release + 23 # Serial release + + +Semantic versioning vs. calendar versioning +=========================================== + +A versioning scheme is a way to interpret version numbers of a package, and to +decide which should be the next version number for a new release of a package. +Two versioning schemes are commonly used for Python packages, semantic +versioning and calendar versioning. + +Semantic versioning is recommended for most new projects. + +Semantic versioning +------------------- + +The idea of *semantic versioning* is to use 3-part version numbers, +*major.minor.maintenance*, where the project author increments: + +- *major* when they make incompatible API changes, +- *minor* when they add functionality in a backwards-compatible manner, and +- *maintenance*, when they make backwards-compatible bug fixes. + +Note that many projects, especially larger ones, do not use strict semantic +versioning since many changes are technically breaking changes but affect only a +small fraction of users. Such projects tend to increment the major number when +the incompatibility is high, rather than for any tiny incompatibility, or to +signal a shift in the project. + +For those projects that do adhere to semantic versioning strictly, this approach +allows users to make use of :ref:`compatible release version specifiers +`, with the ``~=`` operator. For +example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i.e., +it requires at least release X.Y, and allows any later release with greater Y as +long as X is the same. Likewise, ``name ~= X.Y.Z`` is roughly equivalent to +``name >= X.Y.Z, == X.Y.*``, i.e., it requires at least X.Y.Z and allows a later +release with same X and Y but higher Z. + +Python projects adopting semantic versioning should abide by clauses 1-8 of the +`Semantic Versioning 2.0.0 specification `_. + + +Calendar versioning +------------------- + +Semantic versioning is not a suitable choice for all projects, such as those +with a regular time based release cadence and a deprecation process that +provides warnings for a number of releases prior to removal of a feature. + +A key advantage of date-based versioning, or `calendar versioning `_, +is that it is straightforward to tell how old the base feature set of a +particular release is given just the version number. + +Calendar version numbers typically take the form *year.month* (for example, +23.10 for December 2023). + + +Other schemes +------------- + +Serial versioning refers to the simplest possible versioning scheme, which +consists of a single number incremented every release. While serial versioning +is very easy to manage as a developer, it is the hardest to track as an end +user, as serial version numbers convey little or no information regarding API +backwards compatibility. + +Combinations of the above schemes are possible. For example, a project may +combine date based versioning with serial versioning to create a *year.serial* +numbering scheme that readily conveys the approximate age of a release, but +doesn't otherwise commit to a particular release cadence within the year. + + + +Pre-release versioning +====================== + +Regardless of the base versioning scheme, pre-releases for a given final release +may be published as: + +* Zero or more dev releases, denoted with a ".devN" suffix, +* Zero or more alpha releases, denoted with a ".aN" suffix, +* Zero or more beta releases, denoted with a ".bN" suffix, +* Zero or more release candidates, denoted with a ".rcN" suffix. + +Pip and other modern Python package installers ignore pre-releases by default +when deciding which versions of dependencies to install. + + +Local version identifiers +========================= + +Public version identifiers are designed to support distribution via :term:`PyPI +`. Python packaging tools also support the notion +of a :ref:`local version identifier `, which can be +used to identify local development builds not intended for publication, or +modified variants of a release maintained by a redistributor. + +A local version identifier takes the form of a public version identifier, +followed by "+" and a local version label. For example: + +.. code-block:: text + + 1.2.0.dev1+hg.5.b11e5e6f0b0b # 5th VCS commit since 1.2.0.dev1 release + 1.2.1+fedora.4 # Package with downstream Fedora patches applied + + + + +.. _calver: https://calver.org +.. _semver: https://semver.org diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst index f6e41075d..8e9ed564b 100644 --- a/source/guides/distributing-packages-using-setuptools.rst +++ b/source/guides/distributing-packages-using-setuptools.rst @@ -288,125 +288,6 @@ points (see below). - -.. _`Choosing a versioning scheme`: - -Choosing a versioning scheme ----------------------------- - -Standards compliance for interoperability -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Different Python projects may use different versioning schemes based on the needs of that -particular project, but all of them are required to comply with the flexible :pep:`public version -scheme <440#public-version-identifiers>` specified -in :pep:`440` in order to be supported in tools and libraries like ``pip`` -and ``setuptools``. - -Here are some examples of compliant version numbers:: - - 1.2.0.dev1 # Development release - 1.2.0a1 # Alpha Release - 1.2.0b1 # Beta Release - 1.2.0rc1 # Release Candidate - 1.2.0 # Final Release - 1.2.0.post1 # Post Release - 15.10 # Date based release - 23 # Serial release - -To further accommodate historical variations in approaches to version numbering, -:pep:`440` also defines a comprehensive technique for :pep:`version -normalisation <440#normalization>` that maps -variant spellings of different version numbers to a standardised canonical form. - -Scheme choices -~~~~~~~~~~~~~~ - -Semantic versioning (preferred) -******************************* - -For new projects, the recommended versioning scheme is based on `Semantic Versioning -`_, but adopts a different approach to handling pre-releases and -build metadata. - -The essence of semantic versioning is a 3-part MAJOR.MINOR.MAINTENANCE numbering scheme, -where the project author increments: - -1. MAJOR version when they make incompatible API changes, -2. MINOR version when they add functionality in a backwards-compatible manner, and -3. MAINTENANCE version when they make backwards-compatible bug fixes. - -Adopting this approach as a project author allows users to make use of :pep:`"compatible release" -<440#compatible-release>` specifiers, where -``name ~= X.Y`` requires at least release X.Y, but also allows any later release with -a matching MAJOR version. - -Python projects adopting semantic versioning should abide by clauses 1-8 of the -`Semantic Versioning 2.0.0 specification `_. - -Date based versioning -********************* - -Semantic versioning is not a suitable choice for all projects, such as those with a regular -time based release cadence and a deprecation process that provides warnings for a number of -releases prior to removal of a feature. - -A key advantage of date based versioning is that it is straightforward to tell how old the -base feature set of a particular release is given just the version number. - -Version numbers for date based projects typically take the form of YEAR.MONTH (for example, -``12.04``, ``15.10``). - -Serial versioning -***************** - -This is the simplest possible versioning scheme, and consists of a single number which is -incremented every release. - -While serial versioning is very easy to manage as a developer, it is the hardest to track -as an end user, as serial version numbers convey little or no information regarding API -backwards compatibility. - -Hybrid schemes -************** - -Combinations of the above schemes are possible. For example, a project may combine date -based versioning with serial versioning to create a YEAR.SERIAL numbering scheme that -readily conveys the approximate age of a release, but doesn't otherwise commit to a particular -release cadence within the year. - -Pre-release versioning -~~~~~~~~~~~~~~~~~~~~~~ - -Regardless of the base versioning scheme, pre-releases for a given final release may be -published as: - -* zero or more dev releases (denoted with a ".devN" suffix) -* zero or more alpha releases (denoted with a ".aN" suffix) -* zero or more beta releases (denoted with a ".bN" suffix) -* zero or more release candidates (denoted with a ".rcN" suffix) - -``pip`` and other modern Python package installers ignore pre-releases by default when -deciding which versions of dependencies to install. - - -Local version identifiers -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Public version identifiers are designed to support distribution via -:term:`PyPI `. Python's software distribution tools also support -the notion of a :pep:`local version identifier -<440#local-version-identifiers>`, which can be used to -identify local development builds not intended for publication, or modified variants of a release -maintained by a redistributor. - -A local version identifier takes the form ``+``. -For example:: - - 1.2.0.dev1+hg.5.b11e5e6f0b0b # 5th VCS commit since 1.2.0.dev1 release - 1.2.1+fedora.4 # Package with downstream Fedora patches applied - - Working in "development mode" ============================= diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index 202031758..6fe9ffccd 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -108,6 +108,8 @@ aside from always being the lowest possible value in the version ordering. sections. +.. _local-version-identifiers: + Local version identifiers ------------------------- From b5d2d8d658779aa1e9587f1afc319bfeee8ad45a Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sun, 17 Dec 2023 20:39:14 +0100 Subject: [PATCH 2/8] Address review comments --- source/conf.py | 1 + source/discussions/versioning.rst | 102 ++++++++++++------ ...distributing-packages-using-setuptools.rst | 6 ++ 3 files changed, 74 insertions(+), 35 deletions(-) diff --git a/source/conf.py b/source/conf.py index 0e3a93d5e..e61a32451 100644 --- a/source/conf.py +++ b/source/conf.py @@ -143,6 +143,7 @@ "flexx": ("https://flexx.readthedocs.io/en/latest/", None), "flit": ("https://flit.pypa.io/en/stable/", None), "nox": ("https://nox.thea.codes/en/latest/", None), + "numpy": ("https://numpy.org/doc/stable/", None), "openstack": ("https://docs.openstack.org/glance/latest/", None), "packaging": ("https://packaging.pypa.io/en/latest/", None), "pip": ("https://pip.pypa.io/en/latest/", None), diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index c901ff345..082dd1716 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -18,27 +18,47 @@ version identifiers, for which the authoritative reference is the :ref:`specification of version specifiers `. Here are some examples of version numbers: -.. code-block:: text - - 1.2.0.dev1 # Development release - 1.2.0a1 # Alpha Release - 1.2.0b1 # Beta Release - 1.2.0rc1 # Release Candidate - 1.2.0 # Final Release - 1.2.0.post1 # Post Release - 15.10 # Date based release - 23 # Serial release +- A simple version (final release): 1.2.0 +- A development release: 1.2.0.dev1 +- An alpha release: 1.2.0a1 +- A beta release: 1.2.0b1 +- A release candidate: 1.2.0rc1 +- A post-release: 1.2.0.post1 +- A post-release of an alpha release (possible, but discouraged): 1.2.0a1.post1 +- A simple version with only two components: 23.12 +- A simple version with just one component (possible, but discouraged): 42 +- A version with an epoch: 1!1.0 + +Projects can use a cycle of pre-releases to support testing by their users +before a final release. In order, the steps are: alpha releases, beta releases, +release candidates, final release. + +The purpose of development releases is to support releases made early during a +development cycle, for example, a nightly build, or a build from the latest +source in a Linux distribution. + +Post-releases are used to address minor errors in a final release that do not +affect the distributed software, such as correcting an error in the release +notes. They should not be used for bug fixes; these should be done with a new +final release (e.g., incrementing the third component when using semantic +versioning). + +Finally, epochs, a rarely used feature, serve to fix the sorting order when +changing the versioning scheme. For example, if a project is using calendar +versioning, with versions like 23.12, and switches to semantic versioning, with +versions like 1.0, the comparison between 1.0 and 23.12 will go the wrong way. +To correct this, the new version numbers should have an explicit epoch, as in +"1!1.0", in order to be treated as more recent than the old version numbers. Semantic versioning vs. calendar versioning =========================================== -A versioning scheme is a way to interpret version numbers of a package, and to -decide which should be the next version number for a new release of a package. -Two versioning schemes are commonly used for Python packages, semantic -versioning and calendar versioning. +A versioning scheme is a formalized way to interpret the segments of a version +number, and to decide which should be the next version number for a new release +of a package. Two versioning schemes are commonly used for Python packages, +semantic versioning and calendar versioning. -Semantic versioning is recommended for most new projects. Semantic versioning ------------------- @@ -50,14 +70,15 @@ The idea of *semantic versioning* is to use 3-part version numbers, - *minor* when they add functionality in a backwards-compatible manner, and - *maintenance*, when they make backwards-compatible bug fixes. -Note that many projects, especially larger ones, do not use strict semantic -versioning since many changes are technically breaking changes but affect only a -small fraction of users. Such projects tend to increment the major number when -the incompatibility is high, rather than for any tiny incompatibility, or to -signal a shift in the project. +A majority of Python projects use a scheme that resembles semantic +versioning. However, most projects, especially larger ones, do not strictly +adhere to semantic versioning, since many changes are technically breaking +changes but affect only a small fraction of users. Such projects tend to +increment the major number when the incompatibility is high, or to signal a +shift in the project, rather than for any tiny incompatibility, -For those projects that do adhere to semantic versioning strictly, this approach -allows users to make use of :ref:`compatible release version specifiers +For those projects that do use strict semantic versioning, this approach allows +users to make use of :ref:`compatible release version specifiers `, with the ``~=`` operator. For example, ``name ~= X.Y`` is roughly equivalent to ``name >= X.Y, == X.*``, i.e., it requires at least release X.Y, and allows any later release with greater Y as @@ -68,6 +89,13 @@ release with same X and Y but higher Z. Python projects adopting semantic versioning should abide by clauses 1-8 of the `Semantic Versioning 2.0.0 specification `_. +The popular :doc:`Sphinx ` documentation generator is an example +project that uses strict semantic versioning (:doc:`Sphinx versioning policy +`). The famous :doc:`NumPy ` +scientific computing package explicitly uses "loose" semantic versioning, where +releases incrementing the minor version can contain backwards-incompatible API +changes (:doc:`NumPy versioning policy `). + Calendar versioning ------------------- @@ -81,7 +109,10 @@ is that it is straightforward to tell how old the base feature set of a particular release is given just the version number. Calendar version numbers typically take the form *year.month* (for example, -23.10 for December 2023). +23.12 for December 2023). + +:doc:`Pip `, the standard Python package installer, uses calendar +versioning. Other schemes @@ -107,12 +138,13 @@ Regardless of the base versioning scheme, pre-releases for a given final release may be published as: * Zero or more dev releases, denoted with a ".devN" suffix, -* Zero or more alpha releases, denoted with a ".aN" suffix, -* Zero or more beta releases, denoted with a ".bN" suffix, -* Zero or more release candidates, denoted with a ".rcN" suffix. +* Zero or more alpha releases, denoted with a "aN" suffix, +* Zero or more beta releases, denoted with a "bN" suffix, +* Zero or more release candidates, denoted with a "rcN" suffix. Pip and other modern Python package installers ignore pre-releases by default -when deciding which versions of dependencies to install. +when deciding which versions of dependencies to install, unless explicitly +requested, e.g., with ``pip install pkg==1.1a3``. Local version identifiers @@ -125,15 +157,15 @@ used to identify local development builds not intended for publication, or modified variants of a release maintained by a redistributor. A local version identifier takes the form of a public version identifier, -followed by "+" and a local version label. For example: - -.. code-block:: text - - 1.2.0.dev1+hg.5.b11e5e6f0b0b # 5th VCS commit since 1.2.0.dev1 release - 1.2.1+fedora.4 # Package with downstream Fedora patches applied - - +followed by "+" and a local version label. For example, a package with +Fedora-specific patches applied could have the version "1.2.1+fedora.4". +Another example is versions computed by setuptools-scm_, a setuptools plugin +that reads the version from Git data. In a Git repository with some commits +since the latest release, setuptools-scm generates a version like +"0.5.dev1+gd00980f", or if the repository has untracked changes, like +"0.5.dev1+gd00980f.d20231217". .. _calver: https://calver.org .. _semver: https://semver.org +.. _setuptools-scm: https://setuptools-scm.readthedocs.io diff --git a/source/guides/distributing-packages-using-setuptools.rst b/source/guides/distributing-packages-using-setuptools.rst index 8e9ed564b..bf4227aae 100644 --- a/source/guides/distributing-packages-using-setuptools.rst +++ b/source/guides/distributing-packages-using-setuptools.rst @@ -287,6 +287,12 @@ achieve cross-platform compatibility is to use :ref:`console_scripts` entry points (see below). +Choosing a versioning scheme +---------------------------- + +See :ref:`versioning` for information on common version schemes and how to +choose between them. + Working in "development mode" ============================= From e99d27dfce0f6d8b93c019bb723e20a55871041e Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sun, 17 Dec 2023 20:45:15 +0100 Subject: [PATCH 3/8] Merge "Pre-release versioning" into "Valid version numbers" --- source/discussions/versioning.rst | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index 082dd1716..a63d269bc 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -31,7 +31,10 @@ examples of version numbers: Projects can use a cycle of pre-releases to support testing by their users before a final release. In order, the steps are: alpha releases, beta releases, -release candidates, final release. +release candidates, final release. Pip and other modern Python package +installers ignore pre-releases by default when deciding which versions of +dependencies to install, unless explicitly requested (e.g., with +``pip install pkg==1.1a3``). The purpose of development releases is to support releases made early during a development cycle, for example, a nightly build, or a build from the latest @@ -51,6 +54,7 @@ To correct this, the new version numbers should have an explicit epoch, as in "1!1.0", in order to be treated as more recent than the old version numbers. + Semantic versioning vs. calendar versioning =========================================== @@ -131,22 +135,6 @@ doesn't otherwise commit to a particular release cadence within the year. -Pre-release versioning -====================== - -Regardless of the base versioning scheme, pre-releases for a given final release -may be published as: - -* Zero or more dev releases, denoted with a ".devN" suffix, -* Zero or more alpha releases, denoted with a "aN" suffix, -* Zero or more beta releases, denoted with a "bN" suffix, -* Zero or more release candidates, denoted with a "rcN" suffix. - -Pip and other modern Python package installers ignore pre-releases by default -when deciding which versions of dependencies to install, unless explicitly -requested, e.g., with ``pip install pkg==1.1a3``. - - Local version identifiers ========================= From 4d0108284aedcde4a89ad4e1c829b0277f9c281a Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 20 Dec 2023 19:43:52 +0100 Subject: [PATCH 4/8] Link 0ver + blog posts on semver limitations --- source/discussions/versioning.rst | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index a63d269bc..a2d818e87 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -67,7 +67,7 @@ semantic versioning and calendar versioning. Semantic versioning ------------------- -The idea of *semantic versioning* is to use 3-part version numbers, +The idea of *semantic versioning* (or SemVer) is to use 3-part version numbers, *major.minor.maintenance*, where the project author increments: - *major* when they make incompatible API changes, @@ -79,7 +79,8 @@ versioning. However, most projects, especially larger ones, do not strictly adhere to semantic versioning, since many changes are technically breaking changes but affect only a small fraction of users. Such projects tend to increment the major number when the incompatibility is high, or to signal a -shift in the project, rather than for any tiny incompatibility, +shift in the project, rather than for any tiny incompatibility +[#semver-strictness]_. For those projects that do use strict semantic versioning, this approach allows 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 with a regular time based release cadence and a deprecation process that provides warnings for a number of releases prior to removal of a feature. -A key advantage of date-based versioning, or `calendar versioning `_, -is that it is straightforward to tell how old the base feature set of a -particular release is given just the version number. +A key advantage of date-based versioning, or `calendar versioning `_ +(CalVer), is that it is straightforward to tell how old the base feature set of +a particular release is given just the version number. Calendar version numbers typically take the form *year.month* (for example, 23.12 for December 2023). @@ -154,6 +155,22 @@ since the latest release, setuptools-scm generates a version like "0.5.dev1+gd00980f.d20231217". +-------------------------------------------------------------------------------- + + +.. [#semver-strictness] For some personal viewpoints on this issue, see these + blog posts: `by Hynek Schlawak `_, `by Donald Stufft + `_, `by Bernát Gábor `_, `by + Brett Cannon `_. For a humoristic take, read about + ZeroVer_. + + + +.. _zerover: https://0ver.org .. _calver: https://calver.org .. _semver: https://semver.org +.. _semver-bernat-gabor: https://bernat.tech/posts/version-numbers/ +.. _semver-brett-cannon: https://snarky.ca/why-i-dont-like-semver/ +.. _semver-donald-stufft: https://caremad.io/posts/2016/02/versioning-software/ +.. _semver-hynek-schlawack: https://hynek.me/articles/semver-will-not-save-you/ .. _setuptools-scm: https://setuptools-scm.readthedocs.io From 8b02e7f478b58f8c730ba193ae827af482862a5f Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 24 Jan 2024 23:58:45 +0100 Subject: [PATCH 5/8] @sinoroc's review --- source/discussions/versioning.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index a2d818e87..b66553c19 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -34,7 +34,7 @@ before a final release. In order, the steps are: alpha releases, beta releases, release candidates, final release. Pip and other modern Python package installers ignore pre-releases by default when deciding which versions of dependencies to install, unless explicitly requested (e.g., with -``pip install pkg==1.1a3``). +``pip install pkg==1.1a3`` or ``pip install --pre pkg``). The purpose of development releases is to support releases made early during a development cycle, for example, a nightly build, or a build from the latest @@ -80,7 +80,9 @@ adhere to semantic versioning, since many changes are technically breaking changes but affect only a small fraction of users. Such projects tend to increment the major number when the incompatibility is high, or to signal a shift in the project, rather than for any tiny incompatibility -[#semver-strictness]_. +[#semver-strictness]_. Conversely, a bump of the major version number +is sometimes used to signal significant but backwards-compatible new +features. For those projects that do use strict semantic versioning, this approach allows users to make use of :ref:`compatible release version specifiers From 78b83a225117fe33a4dc71494edf6387ba026d2c Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sat, 27 Jan 2024 18:36:17 +0100 Subject: [PATCH 6/8] Address review comments from @webknjaz --- source/discussions/versioning.rst | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index b66553c19..8a738f866 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -16,18 +16,18 @@ needs of that particular project, but in order to be compatible with tools like :ref:`pip`, all of them are required to comply with a flexible format for version identifiers, for which the authoritative reference is the :ref:`specification of version specifiers `. Here are some -examples of version numbers: - -- A simple version (final release): 1.2.0 -- A development release: 1.2.0.dev1 -- An alpha release: 1.2.0a1 -- A beta release: 1.2.0b1 -- A release candidate: 1.2.0rc1 -- A post-release: 1.2.0.post1 -- A post-release of an alpha release (possible, but discouraged): 1.2.0a1.post1 -- A simple version with only two components: 23.12 -- A simple version with just one component (possible, but discouraged): 42 -- A version with an epoch: 1!1.0 +examples of version numbers [#version-examples]_: + +- A simple version (final release): ``1.2.0`` +- A development release: ``1.2.0.dev1`` +- An alpha release: ``1.2.0a1`` +- A beta release: ``1.2.0b1`` +- A release candidate: ``1.2.0rc1`` +- A post-release: ``1.2.0.post1`` +- A post-release of an alpha release (possible, but discouraged): ``1.2.0a1.post1`` +- A simple version with only two components: ``23.12`` +- A simple version with just one component: ``42`` +- A version with an epoch: ``1!1.0`` Projects can use a cycle of pre-releases to support testing by their users before a final release. In order, the steps are: alpha releases, beta releases, @@ -68,11 +68,11 @@ Semantic versioning ------------------- The idea of *semantic versioning* (or SemVer) is to use 3-part version numbers, -*major.minor.maintenance*, where the project author increments: +*major.minor.patch*, where the project author increments: - *major* when they make incompatible API changes, - *minor* when they add functionality in a backwards-compatible manner, and -- *maintenance*, when they make backwards-compatible bug fixes. +- *patch*, when they make backwards-compatible bug fixes. A majority of Python projects use a scheme that resembles semantic versioning. However, most projects, especially larger ones, do not strictly @@ -159,6 +159,8 @@ since the latest release, setuptools-scm generates a version like -------------------------------------------------------------------------------- +.. [#version-examples] Some more examples of unusual version numbers are + given in a `blog post `_ by Seth Larson. .. [#semver-strictness] For some personal viewpoints on this issue, see these blog posts: `by Hynek Schlawak `_, `by Donald Stufft @@ -176,3 +178,4 @@ since the latest release, setuptools-scm generates a version like .. _semver-donald-stufft: https://caremad.io/posts/2016/02/versioning-software/ .. _semver-hynek-schlawack: https://hynek.me/articles/semver-will-not-save-you/ .. _setuptools-scm: https://setuptools-scm.readthedocs.io +.. _versions-seth-larson: https://sethmlarson.dev/pep-440 From bd555c5f759c7be146a31497e8eaa701ecc35e15 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Sat, 27 Jan 2024 18:42:44 +0100 Subject: [PATCH 7/8] Fix reST syntax --- source/discussions/versioning.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index 8a738f866..c91273310 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -160,7 +160,7 @@ since the latest release, setuptools-scm generates a version like -------------------------------------------------------------------------------- .. [#version-examples] Some more examples of unusual version numbers are - given in a `blog post `_ by Seth Larson. + given in a `blog post `_ by Seth Larson. .. [#semver-strictness] For some personal viewpoints on this issue, see these blog posts: `by Hynek Schlawak `_, `by Donald Stufft From 1935669329cd121dbe87e84f7f311805184d8c8b Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 7 Feb 2024 17:44:55 +0100 Subject: [PATCH 8/8] Apply suggestion from @webknjaz MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) --- source/discussions/versioning.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/discussions/versioning.rst b/source/discussions/versioning.rst index c91273310..49fbbf0de 100644 --- a/source/discussions/versioning.rst +++ b/source/discussions/versioning.rst @@ -63,6 +63,22 @@ number, and to decide which should be the next version number for a new release of a package. Two versioning schemes are commonly used for Python packages, semantic versioning and calendar versioning. +.. caution:: + + The decision which version number to choose is up to a + project's maintainer. This effectively means that version + bumps reflect the maintainer's view. That view may differ + from the end-users' perception of what said formalized + versioning scheme promises them. + + There are known exceptions for selecting the next version + number. The maintainers may consciously choose to break the + assumption that the last version segment only contains + backwards-compatible changes. + One such case is when security vulnerability needs to be + addressed. Security releases often come in patch versions + but contain breaking changes inevitably. + Semantic versioning -------------------