Doc: Add version rule to avoid surpises

tomschr · tomschr · commit 7dd624eaaf4c · 2020-05-10T16:57:10.000+02:00
Add a new section "Release Policy" to give a
recommendation.

As with the upcoming major 3 release of semver, a lot of
things have been changed. To avoid any surprises for
our users or even break their code base, a short
version restriction can solve that.

This should help users who wants to stay with release 2.

Basically, it boils down to a line like `semver&gt;=2,&lt;3`.
This can be added in any file which lists dependencies.
diff --git a/docs/install.rst b/docs/install.rst
@@ -1,6 +1,22 @@
 Installing semver
 =================
 
+Release Policy
+--------------
+
+As semver uses `Semantic Versioning`_, breaking changes are only introduced in major
+releases (incremented X in "X.Y.Z").
+
+For users who want to stay with major 2 releases only, add the following version
+restriction::
+
+    semver>=2,<3
+
+This line avoids surprises. You will get any updates within the major 2 release like
+2.9.1, 2.10.0, or above. However, you will never get an update for semver 3.0.0.
+
+You can add this line in your file :file:`setup.py`, :file:`requirements.txt`, or any other
+file that lists your dependencies.
 
 Pip
 ---
@@ -103,3 +119,6 @@ Ubuntu
 2. Install the package::
 
     $ sudo apt-get install python3-semver
+
+
+.. _semantic versioning: http://semver.org/
