Merge pull request #431 from tomschr/version-policy

tomschr · web-flow · commit 9a98394ce402 · 2023-10-09T10:52:21.000+02:00
Clarify version policy for semver
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.`