Doc: Add version rule to avoid surpises

tomschr · tomschr · commit 028f6b186943 · 2020-05-13T20:26:09.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,25 @@
 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.
+
+Keep in mind, as this line avoids any major version updates, you also will never
+get new exciting features or bug fixes.
+
+You can add this line in your file :file:`setup.py`, :file:`requirements.txt`, or any other
+file that lists your dependencies.
 
 Pip
 ---
@@ -17,12 +36,12 @@ For Python 3:
 
     pip3 install semver
 
-If you want to install this specific version, you can use the command :command:`pip`
-with an URL:
+If you want to install this specific version (for example, 2.10.0), use the command :command:`pip`
+with an URL and its version:
 
 .. parsed-literal::
 
-    pip3 install git+https://github.com/python-semver/python-semver.git@|version|
+    pip3 install git+https://github.com/python-semver/python-semver.git@2.10.0
 
 
 Linux Distributions
@@ -103,3 +122,6 @@ Ubuntu
 2. Install the package::
 
     $ sudo apt-get install python3-semver
+
+
+.. _semantic versioning: http://semver.org/
