Cover the PyPI migration in Tool Recommendations (pypa#335)

ncoghlan · web-flow · commit cc80122c49ab · 2017-06-24T17:24:34.000+10:00
During the migration from the legacy PyPI implementation
to Warehouse, `pypi.python.org` and `pypi.org` are
essentially alternative tools for the tasks of publishing,
browsing, downloading and managing packages.

This adds them to the Tool Recommendations page, so
folks have a single place to check to be informed of the
current recommendations, rather than having to try to
keep up with any announcements made at the time the
recommendations change.
diff --git a/scripts/linkmonitor/inventory.yaml b/scripts/linkmonitor/inventory.yaml
@@ -31,18 +31,18 @@
   distributing.html#local-version-identifiers, distributing.html#manifest-in, distributing.html#name,
   distributing.html#package-data, distributing.html#packages, distributing.html#packaging-and-distributing-projects,
   distributing.html#packaging-your-project, distributing.html#platform-wheels, distributing.html#pre-release-versioning,
-  distributing.html#pure-python-wheels, distributing.html#readme-rst, distributing.html#requirements-for-packaging-and-distributing,
-  distributing.html#scheme-choices, distributing.html#scripts, distributing.html#semantic-versioning-preferred,
-  distributing.html#serial-versioning, distributing.html#setup-args, distributing.html#setup-cfg,
-  distributing.html#setup-name, distributing.html#setup-py, distributing.html#source-distributions,
-  distributing.html#standards-compliance-for-interoperability, distributing.html#universal-wheels,
-  distributing.html#upload-your-distributions, distributing.html#uploading-your-project-to-pypi,
-  distributing.html#url, distributing.html#version, distributing.html#wheels, distributing.html#working-in-development-mode,
-  distributing.html#your-package, extensions.html, extensions.html#alternatives-for-low-level-system-access,
-  extensions.html#alternatives-to-handcoded-accelerator-modules, extensions.html#alternatives-to-handcoded-wrapper-modules,
-  extensions.html#an-overview-of-binary-extensions, extensions.html#binary-extensions,
-  extensions.html#building-binary-extensions, extensions.html#contents, extensions.html#disadvantages,
-  extensions.html#implementing-binary-extensions, extensions.html#publishing-binary-extensions,
+  distributing.html#pure-python-wheels, distributing.html#readme-rst, distributing.html#register-your-project,
+  distributing.html#requirements-for-packaging-and-distributing, distributing.html#scheme-choices,
+  distributing.html#scripts, distributing.html#semantic-versioning-preferred, distributing.html#serial-versioning,
+  distributing.html#setup-args, distributing.html#setup-cfg, distributing.html#setup-name,
+  distributing.html#setup-py, distributing.html#source-distributions, distributing.html#standards-compliance-for-interoperability,
+  distributing.html#universal-wheels, distributing.html#upload-your-distributions,
+  distributing.html#uploading-your-project-to-pypi, distributing.html#url, distributing.html#version,
+  distributing.html#wheels, distributing.html#working-in-development-mode, distributing.html#your-package,
+  extensions.html, extensions.html#alternatives-for-low-level-system-access, extensions.html#alternatives-to-handcoded-accelerator-modules,
+  extensions.html#alternatives-to-handcoded-wrapper-modules, extensions.html#an-overview-of-binary-extensions,
+  extensions.html#binary-extensions, extensions.html#building-binary-extensions, extensions.html#contents,
+  extensions.html#disadvantages, extensions.html#implementing-binary-extensions, extensions.html#publishing-binary-extensions,
   extensions.html#setting-up-a-build-environment-on-windows, extensions.html#use-cases,
   glossary.html, glossary.html#glossary, glossary.html#term-binary-distribution, glossary.html#term-built-distribution,
   glossary.html#term-distribution-package, glossary.html#term-egg, glossary.html#term-extension-module,
@@ -97,10 +97,12 @@
   guides/supporting-windows-using-appveyor.html#setting-up, guides/supporting-windows-using-appveyor.html#support-script,
   guides/supporting-windows-using-appveyor.html#support-scripts, guides/supporting-windows-using-appveyor.html#supporting-windows-using-appveyor,
   guides/supporting-windows-using-appveyor.html#testing-with-tox, guides/tool-recommendations.html,
-  guides/tool-recommendations.html#installation-tool-recommendations, guides/tool-recommendations.html#packaging-tool-recommendations,
-  guides/tool-recommendations.html#tool-recommendations, index.html, index.html#get-started,
-  index.html#learn-more, index.html#python-packaging-user-guide, install_requirements_linux.html,
-  install_requirements_linux.html#arch-linux, install_requirements_linux.html#centos-rhel,
+  guides/tool-recommendations.html#browsing-packages, guides/tool-recommendations.html#downloading-packages,
+  guides/tool-recommendations.html#installation-tool-recommendations, guides/tool-recommendations.html#managing-published-packages-and-releases,
+  guides/tool-recommendations.html#packaging-tool-recommendations, guides/tool-recommendations.html#publishing-platform-migration,
+  guides/tool-recommendations.html#publishing-releases, guides/tool-recommendations.html#tool-recommendations,
+  index.html, index.html#get-started, index.html#learn-more, index.html#python-packaging-user-guide,
+  install_requirements_linux.html, install_requirements_linux.html#arch-linux, install_requirements_linux.html#centos-rhel,
   install_requirements_linux.html#debian-ubuntu, install_requirements_linux.html#fedora,
   install_requirements_linux.html#installing-pip-setuptools-wheel-with-linux-package-managers,
   install_requirements_linux.html#opensuse, installing.html, installing.html#contents,
@@ -171,7 +173,8 @@
   tutorials/distributing-packages.html#packages, tutorials/distributing-packages.html#packaging-and-distributing-projects,
   tutorials/distributing-packages.html#packaging-your-project, tutorials/distributing-packages.html#platform-wheels,
   tutorials/distributing-packages.html#pre-release-versioning, tutorials/distributing-packages.html#pure-python-wheels,
-  tutorials/distributing-packages.html#readme-rst, tutorials/distributing-packages.html#requirements-for-packaging-and-distributing,
+  tutorials/distributing-packages.html#readme-rst, tutorials/distributing-packages.html#register-your-project,
+  tutorials/distributing-packages.html#requirements-for-packaging-and-distributing,
   tutorials/distributing-packages.html#scheme-choices, tutorials/distributing-packages.html#scripts,
   tutorials/distributing-packages.html#semantic-versioning-preferred, tutorials/distributing-packages.html#serial-versioning,
   tutorials/distributing-packages.html#setup-args, tutorials/distributing-packages.html#setup-cfg,
diff --git a/source/guides/tool-recommendations.rst b/source/guides/tool-recommendations.rst
@@ -43,6 +43,80 @@ Packaging Tool Recommendations
   to :term:`PyPI <Python Package Index (PyPI)>`.
 
 
+Publishing Platform Migration
+=============================
+
+The original Python Package Index implementation (hosted at
+`pypi.python.org <https://pypi.python.org>`_) is being phased out in favour
+of an updated implementation hosted at `pypi.org <https://pypi.org>`_. Both
+interfaces share a common database backend and file store, allowing the latter
+to assume more default responsibilities as it becomes more capable.
+
+Users consistently using the latest versions of the recommended tools above
+with their default settings don't need to worry about this migration, but
+users running older versions, or not using the default settings, will need
+to update their configurations in line with the recommendations below.
+
+
+Publishing releases
+-------------------
+
+``pypi.org`` became the default upload platform in September 2016.
+
+Uploads through ``pypi.python.org`` will be *switched off* on **July 3, 2017**.
+
+The default upload settings switched to ``pypi.org`` in the following versions:
+
+* ``twine`` 1.8.0
+* ``setuptools`` 27.0.0
+* Python 2.7.13 (``distutils`` update)
+* Python 3.4.6 (``distutils`` update)
+* Python 3.5.3 (``distutils`` update)
+* Python 3.6.0 (``distutils`` update)
+
+
+Browsing packages
+-----------------
+
+``pypi.python.org`` is currently still the default interface for browsing packages
+(used in links from other PyPA documentation, etc).
+
+``pypi.org`` is fully functional for purposes of browsing available packages, and
+some users may choose to opt in to using it.
+
+``pypi.org`` is expected to become the default recommended interface for browsing
+once the limitations in the next two sections are addressed (at which point
+attempts to access ``pypi.python.org`` will automatically be redirected to
+``pypi.org``).
+
+
+Downloading packages
+--------------------
+
+``pypi.python.org`` is currently still the default host for downloading packages.
+
+``pypi.org`` is fully functional for purposes of downloading packages, and some users
+may choose to opt in to using it, but its current hosting setup isn't capable of
+handling the full bandwidth requirements of being the default download source (even
+after accounting for the Fastly CDN).
+
+``pypi.org`` is expected to become the default host for downloading packages once
+it has been redeployed into an environment capable of handling the associated
+network load.
+
+
+Managing published packages and releases
+----------------------------------------
+
+``pypi.python.org`` provides an interface for logged in users to manage their
+published packages and releases.
+
+``pypi.org`` does not currently provide such an interface.
+
+The missing capabilities are being tracked as part of the
+`Shut Down Legacy PyPI <https://github.com/pypa/warehouse/milestone/7>`_
+milestone.
+
 ----
 
 .. [1] There are some cases where you might choose to use ``easy_install`` (from
diff --git a/source/tutorials/distributing-packages.rst b/source/tutorials/distributing-packages.rst
@@ -784,6 +784,8 @@ can create an account
 
   **Be aware that this stores your password in plaintext.**
 
+.. _register-your-project:
+
 Upload your distributions
 -------------------------
 
