python-semver
diff --git a/‎README.rst
Copy file name to clipboardExpand all lines: README.rst
-5Lines changed: 0 additions & 5 deletions b/‎README.rst
Copy file name to clipboardExpand all lines: README.rst
-5Lines changed: 0 additions & 5 deletions
diff --git a/‎docs/index.rst
Copy file name to clipboardExpand all lines: docs/index.rst
+1Lines changed: 1 addition & 0 deletions b/‎docs/index.rst
Copy file name to clipboardExpand all lines: docs/index.rst
+1Lines changed: 1 addition & 0 deletions
diff --git a/‎docs/migratetosemver3.rst
Copy file name to clipboard
+42Lines changed: 42 additions & 0 deletions b/‎docs/migratetosemver3.rst
Copy file name to clipboard
+42Lines changed: 42 additions & 0 deletions
@@ -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:
 
 
@@ -11,6 +11,7 @@ Semver |version| -- Semantic Versioning
 
    install
    usage
+   migratetosemver3
    development
    api
 
 
@@ -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