Document migration from semver2 to semver3

tomschr · tomschr · commit bb2cb90b4722 · 2020-11-01T16:14:08.000+01:00
Create a separate file to describe how to migrate to new
semver3.
diff --git a/README.rst b/README.rst
@@ -30,11 +30,6 @@ A Python module for `semantic versioning`_. Simplifies comparing versions.
 .. |MAINT| replace:: ``maint/v2``
 .. _MAINT: https://github.com/python-semver/python-semver/tree/maint/v2
 
-.. note::
-
-    The :class:`VersionInfo` has been renamed to :class:`Version`. An
-    alias has been created to preserve compatibility but the use of the old
-    name has been deprecated.
 
 The module follows the ``MAJOR.MINOR.PATCH`` style:
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,6 +11,7 @@ Semver |version| -- Semantic Versioning
 
    install
    usage
+   migratetosemver3
    development
    api
 
diff --git a/docs/migratetosemver3.rst b/docs/migratetosemver3.rst
@@ -0,0 +1,42 @@
+.. _semver2-to-3:
+
+Migrating from semver2 to semver3
+=================================
+
+This chapter describes the visible differences for
+users and how your code stays compatible for semver3.
+
+Although the development team tries to make the transition
+to semver3 as smooth as possible, at some point change
+is inevitable.
+
+For a more detailed overview of all the changes, refer
+to our :ref:`changelog`.
+
+
+Use Version instead of VersionInfo
+----------------------------------
+
+The :class:`VersionInfo` has been renamed to :class:`Version`
+to have a more succinct name.
+An alias has been created to preserve compatibility but
+using old name has been deprecated.
+
+If you still need the old version, use this line:
+
+.. code-block:: python
+
+   from semver.version import Version as VersionInfo
+
+
+
+Use semver.cli instead of semver
+--------------------------------
+
+All functions related to CLI parsing are moved to :mod:`semver.cli`.
+If you are such functions, like :func:`semver.cmd_bump <semver.cli.cmd_bump>`,
+import it from :mod:`semver.cli` in the future:
+
+.. code-block:: python
+
+   from semver.cli import cmd_bump
