Add API changes to migration doc (#3240)

* Fix whitespace

* Add API changes and announce list to migration doc

Fix #3238.

* Improve migration guidance

docs/api-reference/feeds.rst

@@ -20,6 +20,7 @@ Available at https://pypi.org/rss/updates.xml, this feed provides the latest
 newly created releases for individual projects on PyPI, including the project
 name and description, release version, and a link to the release page.
 
+
 Project and release activity details
 ------------------------------------
 

docs/api-reference/integration-guide.rst

@@ -4,6 +4,11 @@ Integration guide
 We provide multiple APIs to help you integrate with PyPI; see
 :doc:`index`.
 
+Many tools already integrate with PyPI, uploading packages or
+retrieving data; see `the Python Packaging Guide's tool
+recommendations
+<https://packaging.python.org/guides/tool-recommendations/>`_.
+
 
 Migrating to the new PyPI
 -------------------------
@@ -20,20 +25,38 @@ Here are some tips.
 
 * If your client correctly follows redirects, you can replace
   ``pypi.python.org`` in your links with ``pypi.org`` and everything
-  should just work. ``https://pypi.org/pypi/{name}`` (with or
-  without a trailing slash) redirects to
-  ``https://pypi.org/project/{name}/``.
+  should just work. For instance, the project detail page
+  ``https://pypi.org/pypi/{name}`` (with or without a trailing slash)
+  redirects to ``https://pypi.org/project/{name}/``.
 
-* In case you prefer a shorter URL: feel free to link to
-  ``https://pypi.org/p/{name}/``, which will redirect to
+* Shorter URL: ``https://pypi.org/p/{name}/`` will redirect to
   ``https://pypi.org/project/{name}/``.
 
+* Documentation upload: Users can no longer use ``doc_upload`` in the
+  API to upload documentation ZIP files, separate from packages, to be
+  hosted at pythonhosted.org (`discussion
+  <https://github.com/pypa/warehouse/issues/509>`_).
+
+* All APIs: `access is HTTPS-only
+  <https://mail.python.org/pipermail/distutils-sig/2017-October/031712.html>`_
+  (changed in October 2017). And pypi.org honors an ``Accept-Encoding:
+  gzip`` header, whereas pypi.python.org ignored it.
+
 * JSON API: ``https://pypi.org/pypi/{name}/json`` returns the
-  expected JSON response directly -- see :doc:`json`.
+  expected JSON response directly. See :doc:`json`.
+
+* XML-RPC API: see :ref:`changes-to-legacy-api`.
+
+* Packages/updates RSS feeds: ``https://pypi.org/pypi?%3Aaction=rss``
+  redirects to ``https://pypi.org/rss/updates.xml``, and
+  ``https://pypi.org/pypi?%3Aaction=packages_rss`` redirects to
+  ``https://pypi.org/rss/packages.xml``. See :doc:`feeds` for
+  descriptions. `The data differs from the legacy feed data because
+  the new feeds are standards-compliant and fix inaccuracies in the
+  publication date <https://github.com/pypa/warehouse/issues/3238>`_.
 
-* Package upload RSS feed: ``https://pypi.org/pypi?%3Aaction=rss``
-  redirects to ``https://pypi.org/rss/updates.xml``. See
-  :doc:`feeds`.
+* Subscribe to `the PyPI announcement list (low-traffic)
+  <https://mail.python.org/mm3/mailman3/lists/pypi-announce.python.org/>`_.
 
 If you're a PyPI end user or packager looking to migrate to the new
 PyPI, please see `the official Python Packaging User Guide on

docs/api-reference/xml-rpc.rst

@@ -31,6 +31,8 @@ Example usage::
     'upload_time': <DateTime '20060427T06:26:04' at 912fdec>,
     'url': 'https://pypi.org/packages/any/r/roundup/roundup-1.1.2.win32.exe'}]
 
+.. _changes-to-legacy-api:
+
 Changes to Legacy API
 ---------------------
 
@@ -43,8 +45,9 @@ never fully supported anyway.
 ``release_downloads`` and ``top_packages`` No longer supported. Please
 use `Google BigQuery
 <https://mail.python.org/pipermail/distutils-sig/2016-May/028986.html>`_
-instead (`tips
-<https://langui.sh/2016/12/09/data-driven-decisions/>`_).
+instead (`guidance
+<https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
+`tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).
 
 Package Querying
 ----------------