Add resolver docs

docs/html/user_guide.rst

@@ -772,6 +772,186 @@ archives are built with identical packages.
 
 .. _`Using pip from your program`:
 
+Fixing conflicting dependencies
+===============================
+
+The purpose of this section of documentation is to provide practical suggestions to
+pip users who encounter an error where pip cannot install their
+specified packages due to conflicting dependencies (a
+``ResolutionImpossible`` error).
+
+This documentation is specific to the new resolver, which you can use
+with the flag ``--unstable-feature=resolver``.
+
+Understanding your error message
+--------------------------------
+
+When you get a ``ResolutionImpossible`` error, you might see something
+like this:
+
+::
+
+    pip install package_coffee==0.44.1 package_tea==4.3.0
+
+::
+
+    Due to conflicting dependencies pip cannot install package_coffee and
+    package_tea:
+    - package_coffee depends on package_water<3.0.0,>=2.4.2
+    - package_tea depends on package_water==2.3.1
+
+In this example, pip cannot install the packages you have requested,
+because they each depend on different versions of the same package
+(``package_water``):
+
+- ``package_coffee`` version ``0.44.1`` depends on a version of
+  ``package_water`` that is less than ``3.0.0`` but greater than or equal to
+  ``2.4.2``
+- ``package_tea`` version ``4.3.0`` depends on version ``2.3.1`` of
+  ``package_water``
+
+Sometimes these messages are straightforward to read, because they use
+commonly understood comparison operators to specify the required version
+(e.g. ``<`` or ``>``).
+
+However, Python packaging also supports some more complex ways for
+specifying package versions (e.g. ``~=`` or ``*``):
+
+.. csv-table::
+  :header: "Operator", "Description", "Example"
+
+  ``>``, "Any version greater than the specified version", "``>3.1``: any
+  version greater than 3.1"
+  ``<``, "Any version less than the specified version", "``<3.1``: any version
+  less than ``3.1``"
+  ``<=``, "Any version less than or equal to the specified version", "``<=3.1``:
+  any version less than or equal to ``3.1``"
+  ``>=``, "Any version greater than or equal to the specified
+  version", "``>=3.1``: version ``3.1`` and greater"
+  ``==``, "Exactly the specified version", ``==3.1``: only version ``3.1``
+  ``!=``, "Any version not equal to the specified version", "``!=3.1``: any
+  version other than ``3.1``"
+  ``~=``, "Any compatible release. Compatible releases are releases that are
+  within the same major or minor version, assuming the package author is using
+  semantic versioning.", "``~=3.1``: version ``3.1`` or later, but not version
+  ``4.0`` or later. ``~=3.1.2``: version ``3.1.2`` or later, but not
+  version ``3.2.0`` or later."
+  ``*``,Can be used at the end of a version number to represent "all", "``== 3.
+  1.*``: any version that starts with ``3.1``. Equivalent to ``~=3.1.0``."
+
+The detailed specification of supported comparison operators can be
+found in :pep:`440`.
+
+Possible solutions
+------------------
+
+The solution to your error will depend on your individual use case. Here
+are some things to try:
+
+1. Audit your top level requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As a first step it is useful to audit your project and remove any
+unnecessary or out of date requirements (e.g. from your ``setup.py`` or
+``requirements.txt`` files). Removing these can significantly reduce the
+complexity of your dependency tree, thereby reducing opportunities for
+conflicts to occur.
+
+2. Loosen your top level requirements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes the packages that you have asked pip to install are
+incompatible because you have been too strict when you specified the
+package version.
+
+In our first example both ``package_coffee`` and ``package_tea`` have been
+*pinned* to use specific versions
+(``package_coffee==0.44.1b0 package_tea==4.3.0``).
+
+To find a version of both ``package_coffee`` and ``package_tea`` that depend on
+the same version of ``package_water``, you might consider:
+
+-  Loosening the range of packages that you are prepared to install
+   (e.g. ``pip install "package_coffee>0.44.*" "package_tea>4.0.0"``)
+-  Asking pip to install *any* version of ``package_coffee`` and ``package_tea``
+   by removing the version specifiers altogether (e.g.
+   ``pip install package_coffee package_tea``)
+
+In the second case, pip will automatically find a version of both
+``package_coffee`` and ``package_tea`` that depend on the same version of
+``package_water``, installing:
+
+-  ``package_coffee 0.46.0b0``, which depends on ``package_water 2.6.1``
+-  ``package_tea 4.3.0`` which *also* depends on ``package_water 2.6.1``
+
+If you want to prioritize one package over another, you can add version
+specifiers to *only* the more important package::
+
+    pip install package_coffee==0.44.1b0 package_tea
+
+This will result in:
+
+- ``package_coffee 0.44.1b0``, which depends on ``package_water 2.6.1``
+- ``package_tea 4.1.3`` which also depends on ``package_water 2.6.1``
+
+Now that you have resolved the issue, you can repin the compatible
+package versions as required.
+
+3. Loosen the requirements of your dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Assuming that you cannot resolve the conflict by loosening the version
+of the package you require (as above), you can try to fix the issue on
+your *dependency* by:
+
+-  Requesting that the package maintainers loosen *their* dependencies
+-  Forking the package and loosening the dependencies yourself
+
+.. warning::
+
+   If you choose to fork the package yourself, you are *opting out* of
+   any support provided by the package maintainers. Proceed at your own risk!
+
+4. All requirements are loose, but a solution does not exist
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes it's simply impossible to find a combination of package
+versions that do not conflict. Welcome to `dependency hell`_.
+
+In this situation, you could consider:
+
+-  Using an alternative package, if that is acceptable for your project.
+   See `Awesome Python`_ for similar packages.
+-  Refactoring your project to reduce the number of dependencies (for
+   example, by breaking up a monolithic code base into smaller pieces)
+
+Getting help
+------------
+
+If none of the suggestions above work for you, we recommend that you ask
+for help on:
+
+-  `Python user Discourse`_
+-  `Python user forums`_
+-  `Python developers Slack channel`_
+-  `Python IRC`_
+-  `Stack Overflow`_
+
+See `"How do I ask a good question?"`_ for tips on asking for help.
+
+Unfortunately, **the pip team cannot provide support for individual
+dependency conflict errors**. Please *only* open a ticket on the `pip
+issue tracker`_ if you believe that your problem has exposed a bug in pip.
+
+.. _dependency hell: https://en.wikipedia.org/wiki/Dependency_hell>
+.. _Awesome Python: https://python.libhunt.com/
+.. _Python user Discourse: https://discuss.python.org/c/users/7
+.. _Python user forums: https://www.python.org/community/forums/
+.. _Python developers Slack channel: https://pythondev.slack.com/
+.. _Python IRC: https://www.python.org/community/irc/
+.. _Stack Overflow: https://stackoverflow.com/questions/tagged/python
+.. _"How do I ask a good question?": https://stackoverflow.com/help/how-to-ask
+.. _pip issue tracker: https://github.com/pypa/pip/issues
 
 Using pip from your program
 ===========================