From 20663fc993951ccabe41b4d3744418c37f4a3644 Mon Sep 17 00:00:00 2001 From: Sumana Harihareswara Date: Mon, 3 Aug 2020 10:27:28 -0400 Subject: [PATCH] Docs: Add details on old resolver deprecation and removal Relevant to #8371, #6536, #8076. Signed-off-by: Sumana Harihareswara --- docs/html/development/release-process.rst | 3 +++ docs/html/user_guide.rst | 30 +++++++++++++++++++---- news/8371.doc | 1 + 3 files changed, 29 insertions(+), 5 deletions(-) create mode 100644 news/8371.doc diff --git a/docs/html/development/release-process.rst b/docs/html/development/release-process.rst index cbfbce4ad..44197955e 100644 --- a/docs/html/development/release-process.rst +++ b/docs/html/development/release-process.rst @@ -2,6 +2,7 @@ Release process =============== +.. _`Release Cadence`: Release Cadence =============== @@ -72,6 +73,8 @@ only bugs will be considered, and merged (subject to normal review processes). Note that there may be delays due to the lack of developer resources for reviewing such pull requests. +.. _`Feature Flags`: + Feature Flags ============= diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 31887a288..11bdc5818 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -1223,18 +1223,37 @@ Specific things we'd love to get feedback on: Please let us know through the `resolver testing survey`_. +Deprecation timeline +-------------------- + +We plan for the resolver changeover to proceed as follows, using +:ref:`Feature Flags` and following our :ref:`Release Cadence`: + +* pip 20.2: a beta of the new resolver is available, opt-in, using + the flag ``--use-feature=2020-resolver``. pip defaults to + legacy behavior. + +* 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 21.0: pip uses new resolver, and the old resolver is no longer + available. + +Since this work will not change user-visible behavior described in the +pip documentation, this change is not covered by the :ref:`Deprecation +Policy`. + Context and followup -------------------- As discussed in `our announcement on the PSF blog`_, the pip team are in the process of developing a new "dependency resolver" (the part of -pip that works out what to install based on your requirements). Since -this work will not change user-visible behavior described in the pip -documentation, this change is not covered by the :ref:`Deprecation -Policy`. +pip that works out what to install based on your requirements). We're tracking our rollout in :issue:`6536` and you can watch for -announcements on the `low-traffic packaging announcements list`_. +announcements on the `low-traffic packaging announcements list`_ and +`the official Python blog`_. .. _freeze: https://pip.pypa.io/en/latest/reference/pip_freeze/ .. _resolver testing survey: https://tools.simplysecure.org/survey/index.php?r=survey/index&sid=989272&lang=en @@ -1242,3 +1261,4 @@ announcements on the `low-traffic packaging announcements list`_. .. _tensorflow: https://pypi.org/project/tensorflow/ .. _low-traffic packaging announcements list: https://mail.python.org/mailman3/lists/pypi-announce.python.org/ .. _our survey on upgrades that create conflicts: https://docs.google.com/forms/d/e/1FAIpQLSeBkbhuIlSofXqCyhi3kGkLmtrpPOEBwr6iJA6SzHdxWKfqdA/viewform +.. _the official Python blog: https://blog.python.org/ diff --git a/news/8371.doc b/news/8371.doc new file mode 100644 index 000000000..ffd991950 --- /dev/null +++ b/news/8371.doc @@ -0,0 +1 @@ +Add details on old resolver deprecation and removal to migration documentation.