docs: Describe --upgrade-strategy and direct requirements explicitly

docs/html/cli/pip_install.rst

@@ -1000,6 +1000,13 @@ Examples
 
          py -m pip install --upgrade SomePackage
 
+    .. note::
+
+      This will guarantee an update to ``SomePackage`` as it is a direct
+      requirement, and possibly upgrade dependencies if their installed
+      versions do not meet the minimum requirements of ``SomePackage``.
+      Any non-requisite updates of its dependencies (indirect requirements)
+      will be affected by the ``--upgrade-strategy`` command.
 
 #. Install a local project in "editable" mode. See the section on :ref:`Editable Installs <editable-installs>`.
 

docs/html/development/architecture/upgrade-options.rst

@@ -30,7 +30,8 @@ candidate.
 ``--upgrade-strategy``
 
 This option affects which packages are allowed to be installed. It is only
-relevant if ``--upgrade`` is specified. The base behaviour is to allow
+relevant if ``--upgrade`` is specified (except for the ``to-satisfy-only``
+option mentioned below). The base behaviour is to allow
 packages specified on pip's command line to be upgraded. This option controls
 what *other* packages can be upgraded:
 
@@ -43,9 +44,15 @@ what *other* packages can be upgraded:
   pip command or a requirement file (i.e, they are direct requirements), or
   an upgraded parent needs a later version of the dependency than is
   currently installed.
-* ``to-satisfy-only`` (**undocumented**) - packages are not upgraded (not
-  even direct requirements) unless the currently installed version fails to
-  satisfy a requirement (either explicitly specified or a dependency).
+* ``to-satisfy-only`` (**undocumented, please avoid**) - packages are not
+  upgraded (not even direct requirements) unless the currently installed
+  version fails to satisfy a requirement (either explicitly specified or a
+  dependency).
+
+  * This is actually the "default" upgrade strategy when ``--upgrade`` is
+    *not set*, i.e. ``pip install AlreadyInstalled`` and
+    ``pip install --upgrade --upgrade-strategy=to-satisfy-only AlreadyInstalled``
+    yield the same behavior.
 
 ``--force-reinstall``
 

docs/html/user_guide.rst

@@ -825,6 +825,21 @@ strategies supported:
 The default strategy is ``only-if-needed``. This was changed in pip 10.0 due to
 the breaking nature of ``eager`` when upgrading conflicting dependencies.
 
+It is important to note that ``--upgrade`` affects *direct requirements* (e.g.
+those specified on the command-line or via a requirements file) while
+``--upgrade-strategy`` affects *indirect requirements* (dependencies of direct
+requirements).
+
+As an example, say ``SomePackage`` has a dependency, ``SomeDependency``, and
+both of them are already installed but are not the latest avaialable versions:
+
+- ``pip install SomePackage``: will not upgrade the existing ``SomePackage`` or
+  ``SomeDependency``.
+- ``pip install --upgrade SomePackage``: will upgrade ``SomePackage``, but not
+  ``SomeDependency`` (unless a minimum requirement is not met).
+- ``pip install --upgrade SomePackage --upgrade-strategy=eager``: upgrades both
+  ``SomePackage`` and ``SomeDependency``.
+
 As an historic note, an earlier "fix" for getting the ``only-if-needed``
 behaviour was:
 

news/9692.doc.rst

@@ -0,0 +1,2 @@
+Describe ``--upgrade-strategy`` and direct requirements explicitly; add a brief
+example.