Merge pull request python-semver#249 from tomschr/feature/doc-release-policy

tomschr · web-flow · commit 0733da7f491e · 2020-05-13T21:04:09.000+02:00
Doc: Add version rule to avoid surpises
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/
