Further updates based on DPO thread

* The addition of the ``Location`` header is now a **MUST**, and better worded to indicate that it
  can be polled in the case of a ``202 Accepted``.
* Added a couple of **FIXME** tags to address removal of nonce and fleshing out the ``Errors``
  section.  See URLs in the text.  DO NOT PROMOTE FROM DRAFT UNTIL THIS IS DONE.
* Reformatted some text.

Author: warsaw

peps/pep-0694.rst

@@ -81,12 +81,9 @@ In addition, there are a number of major issues with the legacy API:
 * Creation of new projects requires the uploading of at least one file, leading to "stub" uploads
   to claim a project namespace.
 
-The new upload API proposed in this PEP provides ways to solve all of these problems,
-either directly or through an extensible approach,
-allowing servers to implement features such as resumable and parallel uploads.
-This upload API this PEP proposes provides
-better error reporting,
-a more robust release testing experience,
+The new upload API proposed in this PEP provides ways to solve all of these problems, either directly or
+through an extensible approach, allowing servers to implement features such as resumable and parallel uploads.
+This upload API this PEP proposes provides better error reporting, a more robust release testing experience,
 and atomic and simultaneous publishing of all release artifacts.
 
 Legacy API
@@ -276,6 +273,8 @@ are determined by the index operator.
 Errors
 ------
 
+**FIXME**: https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/20
+
 All error responses that contain content look like:
 
 .. code-block:: json
@@ -331,6 +330,8 @@ A release starts by creating a new Publishing Session.  To create the session, a
       "nonce": "<string>"
     }
 
+**FIXME: (get rid of ``nonce``): https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/22
+
 
 The request includes the following top-level keys:
 
@@ -528,10 +529,9 @@ If the server is able to immediately complete the Publishing Session, it may do
 (for instance, if it needs to do validation that may take longer than reasonable in a single HTTP
 request), then it may return a ``202 Accepted`` response.
 
-In either case, the server should include a ``Location`` header pointing back to
-the Publishing Session status URL,
-and if the server returned a ``202 Accepted``,
-the client may poll that URL to watch for the status to change.
+The server **MUST** include a ``Location`` header in the response pointing back to the :ref:`Publishing
+Session status <session-status>` URL, which can be used to query the current session status.  If the server
+returned a ``202 Accepted``, polling that URL can be used to watch for session status changes.
 
 If an error occurs, the appropriate ``4xx`` code should be returned, as described in the
 :ref:`session-errors` section.
@@ -683,16 +683,12 @@ the file to be uploaded.  These checks may include, but are not limited to:
 
 - checking if the contents of the ``metadata``, if provided, are valid.
 
-If the server determines that upload should proceed, it will return a ``202 Accepted`` response,
-with the response body below.
-The :ref:`status <session-status>` of the session will also include
-the filename in the ``files`` mapping.
-If the server cannot proceed with an upload because
-the ``mechanism`` supplied by the client is not supported
-it **MUST** return a ``422 Unprocessable Entity``.
-If the server determines the upload cannot proceed,
-it **MUST** return a ``409 Conflict``.
-The server **MAY** allow parallel uploads of files, but is not required to.
+If the server determines that upload should proceed, it will return a ``202 Accepted`` response, with the
+response body below.  The :ref:`status <session-status>` of the session will also include the filename in the
+``files`` mapping.  If the server cannot proceed with an upload because the ``mechanism`` supplied by the
+client is not supported it **MUST** return a ``422 Unprocessable Content``.  The server **MAY** allow parallel
+uploads of files, but is not required to. If the server determines the upload cannot proceed, it **MUST**
+return a ``409 Conflict``.
 
 .. _file-upload-session-response: