From c7591bf973bc4977ab645cda7d67841e20096174 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Sun, 13 Dec 2020 17:25:59 -0500 Subject: [PATCH 1/4] docs: Clarify that old resolver is default with Python 2 Partially addresses #9194. Signed-off-by: Sumana Harihareswara --- README.rst | 13 ++++++++++-- docs/html/development/release-process.rst | 5 +++-- docs/html/index.rst | 13 ++++++++++-- docs/html/user_guide.rst | 24 +++++++++++++---------- 4 files changed, 39 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index d8d12c850da..ef0dd0ecadd 100644 --- a/README.rst +++ b/README.rst @@ -19,7 +19,16 @@ 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. +.. 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: @@ -48,7 +57,7 @@ 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 .. _Issue tracking: https://github.com/pypa/pip/issues diff --git a/docs/html/development/release-process.rst b/docs/html/development/release-process.rst index e8c4f579553..91ce3e23379 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 ce40b49fa6c..1ac460bd9d9 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 e3aa5dc33d2..873d413107f 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -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 ia + 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 From df7a97f3bc9a7bb0b1bcbcd15419468d05beb442 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Sun, 13 Dec 2020 17:27:14 -0500 Subject: [PATCH 2/4] docs: Fix small style issues. Signed-off-by: Sumana Harihareswara --- docs/html/user_guide.rst | 14 +++++++------- news/9269.doc.rst | 1 + 2 files changed, 8 insertions(+), 7 deletions(-) create mode 100644 news/9269.doc.rst diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 873d413107f..e8218fb785d 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. diff --git a/news/9269.doc.rst b/news/9269.doc.rst new file mode 100644 index 00000000000..f8ff14d9428 --- /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. From 8acf6d4a3cd150f54d46f45ef26bb178cfda602c Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Sun, 13 Dec 2020 17:50:45 -0500 Subject: [PATCH 3/4] docs: Fix README for PyPI rendering Signed-off-by: Sumana Harihareswara --- README.rst | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index ef0dd0ecadd..a15de466b7f 100644 --- a/README.rst +++ b/README.rst @@ -19,16 +19,9 @@ We release updates regularly, with a new version every 3 months. Find more detai * `Release notes`_ * `Release process`_ -.. warning:: +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. - 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. +**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: @@ -60,6 +53,7 @@ rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_. .. _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/ From acc0cc9fe331b7f3f81322c212b169c0d014c3ab Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 14 Dec 2020 06:46:14 -0500 Subject: [PATCH 4/4] docs: Fix typo Co-authored-by: Xavier Fernandez --- docs/html/user_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index e8218fb785d..415c9b1e71c 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1854,7 +1854,7 @@ We plan for the resolver changeover to proceed as follows, using * 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 ia + 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