From 083b592c7dee31fbc54ea7a12f6912a772a1a5fa Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Mon, 9 Oct 2023 09:39:10 +0200 Subject: [PATCH] Clarify version policy for semver Integrate additional topic that describes an high level overview about semver v2, v3, and v3 and beyond. Also revise section about "Release Policy" which is related. First mention semver3 and use semver2 later. --- README.rst | 15 ++---------- changelog.d/pr431.doc.rst | 2 ++ docs/index.rst | 1 + docs/install.rst | 21 +++++++--------- docs/version-policy.rst | 50 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 63 insertions(+), 26 deletions(-) create mode 100644 changelog.d/pr431.doc.rst create mode 100644 docs/version-policy.rst diff --git a/README.rst b/README.rst index 122c12a8..ee2ab44d 100644 --- a/README.rst +++ b/README.rst @@ -12,19 +12,8 @@ A Python module to simplify `semantic versioning`_. .. note:: - This project works for Python 3.7 and greater only. If you are - looking for a compatible version for Python 2, use the - maintenance branch |MAINT|_. - - The last version of semver which supports Python 2.7 to 3.5 will be - 2.x.y However, keep in mind, the major 2 release is frozen: no new - features nor backports will be integrated. - - We recommend to upgrade your workflow to Python 3 to gain support, - bugfixes, and new features. - -.. |MAINT| replace:: ``maint/v2`` -.. _MAINT: https://github.com/python-semver/python-semver/tree/maint/v2 + This project works for Python 3.7 and greater only. + Refer to :ref:`version-policy` for more details. The module follows the ``MAJOR.MINOR.PATCH`` style: diff --git a/changelog.d/pr431.doc.rst b/changelog.d/pr431.doc.rst new file mode 100644 index 00000000..ad54c962 --- /dev/null +++ b/changelog.d/pr431.doc.rst @@ -0,0 +1,2 @@ +Clarify version policy for the different semver versions (v2, v3, >v3) +and the supported Python versions. diff --git a/docs/index.rst b/docs/index.rst index 1054c225..0f1f32d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ Semver |version| -- Semantic Versioning migration/index advanced/index contribute/index + version-policy api .. toctree:: diff --git a/docs/install.rst b/docs/install.rst index 5404882f..dee441de 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -6,25 +6,20 @@ Release Policy As semver uses `Semantic Versioning`_, breaking changes are only introduced in major releases (incremented ``X`` in "X.Y.Z"). +Refer to section :ref:`version-policy` for a general overview. -For users who want to stay with major 2 releases only, add the following version -restriction:: +For users who want or need to stay with major 3 releases only, add the +following version restriction (:file:`setup.py`, :file:`requirements.txt`, +or :file:`pyproject.toml`):: - semver>=2,<3 - -This line avoids surprises. You will get any updates within the major 2 release like -2.11.0 or above. However, you will never get an update for semver 3.0.0. + semver>=3,<4 -Keep in mind, as this line avoids any major version updates, you also will never -get new exciting features or bug fixes. +This line avoids surprises. You will get any updates within the major 3 release like 3.1.x and above. However, you will never get an update for semver 4.0.0. -Same applies for semver v3, if you want to get all updates for the semver v3 -development line, but not a major update to semver v4:: +For users who have to stay with major 2 releases only, use the following line:: - semver>=3,<4 + semver>=2,<3 -You can add this line in your file :file:`setup.py`, :file:`requirements.txt`, -:file:`pyproject.toml`, or any other file that lists your dependencies. Pip --- diff --git a/docs/version-policy.rst b/docs/version-policy.rst new file mode 100644 index 00000000..a6eac5cc --- /dev/null +++ b/docs/version-policy.rst @@ -0,0 +1,50 @@ +.. _version-policy: + +Version Policy +============== + +.. |MAINT| replace:: ``maint/v2`` +.. _MAINT: https://github.com/python-semver/python-semver/tree/maint/v2 +.. |CHANGELOG| replace:: ``Changelog`` +.. _CHANGELOG: https://github.com/python-semver/python-semver/blob/maint/v2/CHANGELOG.rst + +The move from v2 to v3 introduced many changes and deprecated module functions. +The main functionality is handled by the :class:`~semver.version.Version` class +now. Find more information in the section :ref:`semver2-to-3`. + + +semver Version 2 +---------------- + +Active development of major version 2 has stopped. No new features nor +backports will be integrated. +We recommend to upgrade your workflow to Python 3 to gain support, +bugfixes, and new features. + +If you still need this old version, use the |MAINT|_ branch. There you +can look for the |CHANGELOG|_ if you need some details about the history. + + +semver Version 3 +---------------- + +We will not intentionally make breaking changes in minor releases of V3. + +Methods marked as ``deprecated`` raise a warning message when used from the :py:mod:`warnings` module. +Check section :ref:`sec_replace_deprecated_functions` to make your code +ready for future major releases. + + +semver Version 3 and beyond +--------------------------- + +Methods that were marked as deprecated will be very likely be removed. + + +Support for Python versions +--------------------------- + +This project will drop support for a Python version when the +following conditions are met: + +* The Python version has reached `EOL `_.