Clarify version policy for semver

tomschr · tomschr · commit 083b592c7dee · 2023-10-09T10:45:08.000+02:00
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.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 <https://devguide.python.org/versions/>`_.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+Clarify version policy for the different semver versions (v2, v3, >v3)`
	`2`	`+and the supported Python versions.`