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 `_.