From 314bfc63b6467ccea5906098b429de9ab7d565cc Mon Sep 17 00:00:00 2001
From: Antti Kaihola <13725+akaihola@users.noreply.github.com>
Date: Sun, 25 Dec 2022 23:38:06 +0200
Subject: [PATCH] Document usage of `~=` "compatible release"

---
 README.rst | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index 9830e2251..dc81687d9 100644
--- a/README.rst
+++ b/README.rst
@@ -128,13 +128,24 @@ in Black documentation, or the article
 How?
 ====
 
-To install, use::
+To install or upgrade, use::
 
-  pip install darker
+  pip install --upgrade darker~=1.6.0
 
 Or, if you're using Conda_ for package management::
 
-  conda install -c conda-forge darker isort
+  conda install -c conda-forge darker~=1.6.0 isort
+  conda update -c conda-forge darker
+
+..
+
+    **Note:** We recommend to use the ``~=`` "`compatible release`_" version specifier
+    to ensure you have the newest Darker before the next compatibility-breaking major
+    release. If a Black update introduces an incompatibility with Darker, we'll issue
+    one Darker point release which prevents upgrading Black, and later a second one
+    which fixes the incompatibility.
+
+    See issue `#382`_ for more information.
 
 The ``darker <myfile.py>`` or ``darker <directory>`` command
 reads the original file(s),
@@ -159,6 +170,8 @@ You can enable additional features with command line options:
 
 .. _Conda: https://conda.io/
 .. _conda-forge: https://conda-forge.org/
+.. _compatible release: https://peps.python.org/pep-0440/#compatible-release
+.. _#382: https://github.com/akaihola/darker/issues/382
 
 
 Example
@@ -571,9 +584,10 @@ do the following:
            hooks:
            -   id: darker
 
-4. install the Git hook scripts::
+4. install the Git hook scripts and update to the newest version::
 
        pre-commit install
+       pre-commit autoupdate
 
 .. _pre-commit: https://pre-commit.com/
 .. _pre-commit Installation: https://pre-commit.com/#installation
@@ -632,7 +646,7 @@ Create a file named ``.github/workflows/darker.yml`` inside your repository with
              options: "--check --diff --color"
              revision: "master..."
              src: "./src"
-             version: "1.6.0"
+             version: "~=1.6.0"
              lint: "flake8,pylint==2.13.1"
 
 There needs to be a working Python environment, set up using ``actions/setup-python``