Add note about install/upgrade behavior to docs

Towards pypa#8115.
brainwane · Oct 27, 2020 · cab055d · cab055d
1 parent a0ec4be
commit cab055d
Show file tree

Hide file tree

Showing 2 changed files with 10 additions and 3 deletions.
diff --git a/docs/html/development/architecture/upgrade-options.rst b/docs/html/development/architecture/upgrade-options.rst
@@ -2,9 +2,10 @@
 Options that control the installation process
 =============================================
 
-When installing packages, pip chooses a distribution file, and installs it in
-the user's environment. There are many choices involved in deciding which file
-to install, and these are controlled by a variety of options.
+When installing packages, pip chooses a distribution file, and
+installs it in the user's environment. There are many choices (which
+are `still evolving`_) involved in deciding which file to install, and
+these are controlled by a variety of options.
 
 
 Controlling what gets installed
@@ -118,3 +119,6 @@ necessarily resolution or what gets installed.
 ``--constraint``
 
 ``--editable <LOCATION>``
+
+
+.. _still evolving: https://github.com/pypa/pip/issues/8115
diff --git a/docs/html/reference/pip_install.rst b/docs/html/reference/pip_install.rst
@@ -36,6 +36,9 @@ pip install has several stages:
 3. Build wheels. All the dependencies that can be are built into wheels.
 4. Install the packages (and uninstall anything being upgraded/replaced).
 
+Note that ``pip install`` prefers to leave the installed version as-is
+unless ``--upgrade`` is specified.
+
 Argument Handling
 -----------------