From 028f6b186943d5086aa1b81873b71fb100701ee8 Mon Sep 17 00:00:00 2001 From: Tom Schraitle Date: Sun, 10 May 2020 16:46:01 +0200 Subject: [PATCH] Doc: Add version rule to avoid surpises 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>=2,<3`. This can be added in any file which lists dependencies. --- docs/install.rst | 28 +++++++++++++++++++++++++--- 1 file changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/install.rst b/docs/install.rst index 5301bb86..fd13aa83 100644 --- 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/ \ No newline at end of file