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

Add a brief example

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:
 
@@ -45,7 +46,8 @@ what *other* packages can be upgraded:
   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).
+  satisfy a requirement (either explicitly specified or a dependency). This
+  is actually the "default" strategy when ``--upgrade`` is not set.
 
 ``--force-reinstall``
 

docs/html/reference/pip_install.rst

@@ -1000,6 +1000,11 @@ Examples
 
          py -m pip install --upgrade SomePackage
 
+    .. note::
+
+      This will only update ``SomePackage`` as it is a direct requirement. Any
+      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/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: