Merge pull request #9269 from brainwane/docs-update-python-2-pip-20-3

Update docs to clarify that old resolver is default with Python 2

5 files changed, 41 insertions, 23 deletions

diff --git a/README.rst b/README.rst
index d8d12c850..a15de466b 100644
--- a/README.rst
+++ b/README.rst
@@ -19,7 +19,9 @@ We release updates regularly, with a new version every 3 months. Find more detai
 * `Release notes`_
 * `Release process`_
 
-In pip 20.3, we're `making a big improvement to the heart of pip`_; `learn more`_. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
+In pip 20.3, we've `made a big improvement to the heart of pip`_; `learn more`_. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
+
+**Note**: pip 21.0, in January 2021, will remove Python 2 support, per pip's `Python 2 support policy`_. Please migrate to Python 3.
 
 If you find bugs, need help, or want to talk to the developers, please use our mailing lists or chat rooms:
 
@@ -48,9 +50,10 @@ rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
 .. _Release process: https://pip.pypa.io/en/latest/development/release-process/
 .. _GitHub page: https://github.com/pypa/pip
 .. _Development documentation: https://pip.pypa.io/en/latest/development
-.. _making a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
+.. _made a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html
 .. _learn more: https://pip.pypa.io/en/latest/user_guide/#changes-to-the-pip-dependency-resolver-in-20-3-2020
 .. _sign up for our user experience research studies: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
+.. _Python 2 support policy: https://pip.pypa.io/en/latest/development/release-process/#python-2-support
 .. _Issue tracking: https://github.com/pypa/pip/issues
 .. _Discourse channel: https://discuss.python.org/c/packaging
 .. _Development mailing list: https://mail.python.org/mailman3/lists/distutils-sig.python.org/
diff --git a/docs/html/development/release-process.rst b/docs/html/development/release-process.rst
index e8c4f5795..91ce3e233 100644
--- a/docs/html/development/release-process.rst
+++ b/docs/html/development/release-process.rst
@@ -70,8 +70,8 @@ their merits.
 Python 2 Support
 ----------------
 
-pip will continue to ensure that it runs on Python 2.7 after the CPython 2.7
-EOL date. Support for Python 2.7 will be dropped, if bugs in Python 2.7 itself
+pip will continue to ensure that it runs on Python 2.7 after the `CPython 2.7
+EOL date`_. Support for Python 2.7 will be dropped, if bugs in Python 2.7 itself
 make this necessary (which is unlikely) or in pip 21.0 (Jan 2021), whichever is
 earlier.
 
@@ -180,3 +180,4 @@ order to create one of these the changes should already be merged into the
 .. _`get-pip repository`: https://github.com/pypa/get-pip
 .. _`psf-salt repository`: https://github.com/python/psf-salt
 .. _`CPython`: https://github.com/python/cpython
+.. _`CPython 2.7 EOL date`: https://www.python.org/doc/sunset-python-2/
diff --git a/docs/html/index.rst b/docs/html/index.rst
index ce40b49fa..1ac460bd9 100644
--- a/docs/html/index.rst
+++ b/docs/html/index.rst
@@ -17,7 +17,16 @@ Please take a look at our documentation for how to install and use pip:
    ux_research_design
    news
 
-In pip 20.3, we're `making a big improvement to the heart of pip`_; :ref:`Resolver changes 2020`. We want your input, so `sign up for our user experience research studies`_ to help us do it right.
+.. warning::
+
+   In pip 20.3, we've `made a big improvement to the heart of pip`_;
+   :ref:`Resolver changes 2020`. We want your input, so `sign up for
+   our user experience research studies`_ to help us do it right.
+
+.. warning::
+
+   pip 21.0, in January 2021, will remove Python 2 support, per pip's
+   :ref:`Python 2 Support` policy. Please migrate to Python 3.
 
 If you find bugs, need help, or want to talk to the developers, please use our mailing lists or chat rooms:
 
@@ -40,7 +49,7 @@ rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_.
 
 .. _package installer: https://packaging.python.org/guides/tool-recommendations/
 .. _Python Package Index: https://pypi.org
-.. _making a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
+.. _made a big improvement to the heart of pip: https://pyfound.blogspot.com/2020/11/pip-20-3-new-resolver.html
 .. _sign up for our user experience research studies: https://pyfound.blogspot.com/2020/03/new-pip-resolver-to-roll-out-this-year.html
 .. _Installation: https://pip.pypa.io/en/stable/installing.html
 .. _Documentation: https://pip.pypa.io/en/stable/
diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst
index e3aa5dc33..415c9b1e7 100644
--- a/docs/html/user_guide.rst
+++ b/docs/html/user_guide.rst
@@ -512,8 +512,8 @@ all users) configuration:
   else :file:`$HOME/.config/pip/pip.conf`.
 * On Windows the configuration file is :file:`%APPDATA%\\pip\\pip.ini`.
 
-There are also a legacy per-user configuration file which is also respected,
-these are located at:
+There is also a legacy per-user configuration file which is also respected.
+To find its location:
 
 * On Unix and macOS the configuration file is: :file:`$HOME/.pip/pip.conf`
 * On Windows the configuration file is: :file:`%HOME%\\pip\\pip.ini`
@@ -1084,7 +1084,7 @@ You can then install from the archive like this::
     $ python -m pip install --force-reinstall --ignore-installed --upgrade --no-index --no-deps $tempdir/*
 
 Note that compiled packages are typically OS- and architecture-specific, so
-these archives are not necessarily portable across macOShines.
+these archives are not necessarily portable across machines.
 
 Hash-checking mode can be used along with this method to ensure that future
 archives are built with identical packages.
@@ -1331,7 +1331,7 @@ Backtracking is not a bug, or an unexpected behaviour. It is part of the
 way pip's dependency resolution process works.
 
 During a pip install (e.g. ``pip install tea``), pip needs to work out
-the package's dependencies (e.g. ``spoon``, ``hot-water``, ``cup`` etc), the
+the package's dependencies (e.g. ``spoon``, ``hot-water``, ``cup`` etc.), the
 versions of each of these packages it needs to install. For each package
 pip needs to decide which version is a good candidate to install.
 
@@ -1466,9 +1466,9 @@ here are a number of ways.
 
 In most cases, pip will complete the backtracking process successfully.
 It is possible this could take a very long time to complete - this may
-not be the preferred option.
+not be your preferred option.
 
-However there is a possibility pip will not be able to find a set of
+However, there is a possibility pip will not be able to find a set of
 compatible versions.
 
 If you'd prefer not to wait, you can interrupt pip (ctrl and c) and use
@@ -1523,7 +1523,7 @@ suitable constraints file.
 4. Be more strict on package dependencies during development
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-For package maintainers during the development, give pip some help by
+For package maintainers during software development, give pip some help by
 creating constraint files for the dependency tree. This will reduce the
 number of versions it will try.
 
@@ -1610,11 +1610,12 @@ of ability. Some examples that you could consider include:
 Changes to the pip dependency resolver in 20.3 (2020)
 =====================================================
 
-pip 20.3 has a new dependency resolver, on by default. (pip 20.1 and
-20.2 included pre-release versions of the new dependency resolver,
-hidden behind optional user flags.) Read below for a migration guide,
-how to invoke the legacy resolver, and the deprecation timeline. We
-also made a `two-minute video explanation`_ you can watch.
+pip 20.3 has a new dependency resolver, on by default for Python 3
+users. (pip 20.1 and 20.2 included pre-release versions of the new
+dependency resolver, hidden behind optional user flags.) Read below
+for a migration guide, how to invoke the legacy resolver, and the
+deprecation timeline. We also made a `two-minute video explanation`_
+you can watch.
 
 We will continue to improve the pip dependency resolver in response to
 testers' feedback. Please give us feedback through the `resolver
@@ -1815,7 +1816,7 @@ Specific things we'd love to get feedback on:
 
 *    Cases where the new resolver produces the wrong result,
      obviously. We hope there won't be too many of these, but we'd like
-     to trap such bugs now.
+     to trap such bugs before we remove the legacy resolver.
 
 *    Cases where the resolver produced an error when you believe it
      should have been able to work out what to do.
@@ -1850,12 +1851,15 @@ We plan for the resolver changeover to proceed as follows, using
      ``PIP_USE_FEATURE`` environment variable option, see `issue
      8661`_).
 
-*    pip 20.3: pip defaults to the new resolver, but a user can opt-out
-     and choose the old resolver behavior, using the flag
-     ``--use-deprecated=legacy-resolver``.
+*    pip 20.3: pip defaults to the new resolver in Python 3 environments,
+     but a user can opt-out and choose the old resolver behavior,
+     using the flag ``--use-deprecated=legacy-resolver``. In Python 2
+     environments, pip defaults to the old resolver, and the new one is
+     available using the flag ``--use-feature=2020-resolver``.
 
 *    pip 21.0: pip uses new resolver, and the old resolver is no longer
-     available.
+     available. Python 2 support is removed per our :ref:`Python 2
+     Support` policy.
 
 Since this work will not change user-visible behavior described in the
 pip documentation, this change is not covered by the :ref:`Deprecation
diff --git a/news/9269.doc.rst b/news/9269.doc.rst
new file mode 100644
index 000000000..f8ff14d94
--- /dev/null
+++ b/news/9269.doc.rst
@@ -0,0 +1 @@
+Update documentation to reflect that pip still uses legacy resolver by default in Python 2 environments.