Skip to content

Commit

Permalink
Clarify version policy for semver
Browse files Browse the repository at this point in the history
Integrate additional topic that describes an high level overview
about semver v2, v3, and v3 and beyond.
  • Loading branch information
tomschr committed Oct 9, 2023
1 parent 9391f8a commit 5a377c5
Show file tree
Hide file tree
Showing 4 changed files with 55 additions and 13 deletions.
15 changes: 2 additions & 13 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions changelog.d/pr431.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Clarify version policy for the different semver versions (v2, v3, >v3)
and the supported Python versions.
1 change: 1 addition & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Semver |version| -- Semantic Versioning
migration/index
advanced/index
contribute/index
version-policy
api

.. toctree::
Expand Down
50 changes: 50 additions & 0 deletions docs/version-policy.rst
Original file line number Diff line number Diff line change
@@ -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/>`_.

0 comments on commit 5a377c5

Please sign in to comment.