Beta FAQ update (#3346)

* Add XML-RPC deprecation notice to API migration doc

* Announce beta in help pages

Ref. #2518.

Congratulations to us!

* Clarify advice on switching to Warehouse

Author: brainwane

README.rst

@@ -16,7 +16,7 @@ You can run Warehouse locally using ``docker`` and ``docker-compose``. See
 `Getting started <https://warehouse.readthedocs.io/development/getting-started/>`__
 in the documentation for instructions on how to set it up.
 
-You can try a pre-production deployment of Warehouse at `pypi.org`_.
+You can try a beta deployment of Warehouse at `pypi.org`_.
 
 Discussion
 ----------

docs/api-reference/integration-guide.rst

@@ -14,7 +14,10 @@ Migrating to the new PyPI
 -------------------------
 
 If your site/service used to link or upload to pypi.python.org, you
-should start using pypi.org instead.
+should prepare to start using pypi.org instead. Subscribe to `the PyPI
+announcement list (low-traffic)
+<https://mail.python.org/mm3/mailman3/lists/pypi-announce.python.org/>`_
+to find out when you should switch permanently.
 
 Here are some tips.
 
@@ -45,7 +48,10 @@ Here are some tips.
 * JSON API: ``https://pypi.org/pypi/{name}/json`` returns the
   expected JSON response directly. See :doc:`json`.
 
-* XML-RPC API: see :ref:`changes-to-legacy-api`.
+* XML-RPC API: see :ref:`changes-to-legacy-api`. Will be deprecated in
+  the future; switch to the RSS or JSON APIs. If you depend on an
+  XML-RPC call that our other APIs do not support, please <a
+  href="https://pypi.org/help/#feedback">tell us</a>.
 
 * Packages/updates RSS feeds: ``https://pypi.org/pypi?%3Aaction=rss``
   redirects to ``https://pypi.org/rss/updates.xml``, and

docs/index.rst

@@ -15,8 +15,8 @@ Contents:
 Warehouse is a new code base that implements a `Python package index
 (repository)`_.  It is being `actively developed`_ and will eventually
 power PyPI_ and replace an older code base that is currently powering
-PyPI.  You can see Warehouse in production at https://pypi.org/ and
-you can read the `Warehouse roadmap`_.
+PyPI.  You can see a beta version of Warehouse at https://pypi.org/
+and you can read the `Warehouse roadmap`_.
 
 The goal is to improve PyPI by making it:
 

warehouse/templates/pages/help.html

@@ -41,7 +41,7 @@
 {% macro maintainers() %}Who maintains PyPI?{% endmacro %}
 {% macro sponsors() %}What powers PyPI?{% endmacro %}
 {% macro availability() %}Can I depend on PyPI being available?{% endmacro %}
-{% macro preproduction() %}What does pre-production mean?{% endmacro %}
+{% macro beta() %}What does beta mean?{% endmacro %}
 {% macro contributing() %}How can I contribute to PyPI?{% endmacro %}
 {% block title %}Help{% endblock %}
 
@@ -92,7 +92,7 @@ <h2><a href="#about">About</a></h2>
           <li><a href="#maintainers">{{ maintainers() }}</a></li>
           <li><a href="#sponsors">{{ sponsors() }}</a></li>
           <li><a href="#availability">{{ availability() }}</a></li>
-          <li><a href="#preproduction">{{ preproduction() }}</a></li>
+          <li><a href="#beta">{{ beta() }}</a></li>
           <li><a href="#contributing">{{ contributing() }}</a></li>
         </ul>
       </section>
@@ -293,23 +293,24 @@ <h3 id="availability">{{ availability() }}</h3>
           PyPI is heavily cached and distributed via CDN thanks to our sponsor <a href="https://www.fastly.com/" target="_blank" rel="noopener">Fastly</a> and thus is generally available globally. However, as could be expected for a giant distributed system, things can and sometimes do go wrong. If you have high availability requirements for your package index, consider either a <a href="#mirroring">mirror</a> or a <a href="#private-indices">private index</a>.
         </p>
 
-        <h3 id="preproduction">{{ preproduction() }}</h3>
+        <h3 id="beta">{{ beta() }}</h3>
         <p>
-          'Pre-production' indicates that you are using a version of this software that is not fully tested and 'production ready'. This means:
+          'Beta' indicates you are using a version of PyPI that is robust, but not <i>fully</i> tested and 'production ready'. This means:
         </p>
         <ul>
           <li>The UI may return unusual or erroneous results</li>
           <li>Performance may not yet be optimised</li>
-          <li>Some features that you use on the old interface may be missing</li>
+          <li>Some features that you used in <a href="https://pypi.python.org">the old interface (pypi.python.org)</a> may be missing</li>
+          <li>We <a href="#feedback">need your feedback</a> to get the site production ready</li>
         </ul>
         <p>
-          While we are in pre-production, our infrastructure cannot yet support all of the traffic generated by our users running <code>pip install</code>. We therefore ask that you do not use this version of PyPI for production codebases.
+          While we are in beta, the pypi.org infrastructure cannot yet support all of the API traffic generated by our users running <code>pip install</code>, so don't explicitly point to it in automated production setups. But <a href="https://wiki.python.org/psf/PackagingWG/PyPIBetaAnnouncement">we want you to try it and test it</a>, and we're occasionally redirecting portions of that traffic in load tests we announce <a href="http://status.python.org/">on our status page</a>.
         </p>
         <p>
-          On the other hand, uploads are working well, and project maintainers and owners should use this version of PyPI over the legacy site, which no longer supports this function.
+          Uploads, search, and release management are working well, and project maintainers and owners should use this version of PyPI over the legacy site, which no longer supports uploading releases.
         </p>
         <p>
-          Please see <a href="https://wiki.python.org/psf/WarehouseRoadmap">our development roadmap</a> to understand what features will be available next.
+          Please see <a href="https://wiki.python.org/psf/WarehouseRoadmap">our development roadmap</a> to understand what features will be available next, and <a href="https://wiki.python.org/psf/PackagingWG/PyPIBetaAnnouncement">the beta announcement</a> for more context on the beta. To learn when the site launches (goes from beta to production), <a href="https://mail.python.org/mm3/mailman3/lists/pypi-announce.python.org/">subscribe to the announcement email list</a>.
         </p>
 
         <h3 id="contributing">{{ contributing() }}</h3>