PEP 807: split rationale/motivation

Signed-off-by: William Woodruff <william@astral.sh>

Author: woodruffw

peps/pep-0807.rst

@@ -23,8 +23,8 @@ of Trusted Publishing, while allowing other indices to implement the same
 scheme in a manner that is discoverable by and interoperable with existing
 Python package uploading clients.
 
-Rationale and Motivation
-========================
+Motivation
+==========
 
 "Trusted Publishing" is PyPI's term of art for using the
 `OpenID Connect (OIDC) standard <https://openid.net/connect/>`_
@@ -53,6 +53,33 @@ clients (like `twine <https://twine.readthedocs.io/en/stable/>`_ and
 between indices (leading to an accretion of hacks) or continue to reject
 non-PyPI implementations of Trusted Publishing.
 
+Rationale
+=========
+
+The lack of an existing standard for Trusted Publishing is the primary
+rationale for this PEP.
+
+The design proposed in this PEP closely follows PyPI's existing implementation,
+with an added layer of `discovery <Trusted Publishing Discovery>`__
+that enables uploading clients to determine whether an arbitrary index
+supports Trusted Publishing without making PyPI-specific assumptions.
+
+The rationale for this design is as follows:
+
+1. The existing (unstandardized) implementation of Trusted Publishign on PyPI
+   has a proven track record, and is already widely adopted in uploading tools.
+   A significant deviation from the existing design would introduce
+   unnecessary compatibility risks.
+2. The discovery mechanism proposed in this PEP is designed to be
+   consistent with existing standards for machine-to-machine protocols,
+   namely :rfc:`8615` (Well-Known URIs). Additionally, this discovery mechanism
+   is designed to allow multiple indices to be hosted under a single
+   domain, which is a common topology for third-party index hosts.
+
+In sum, the rationale for this PEP is to standardize PyPI's existing
+interfaces *and* make them discoverable while allowing index hosts
+that don't match PyPI's topology to implement Trusted Publishing.
+
 Specification
 =============
 
@@ -168,15 +195,16 @@ error code in the 400 or 500 range to indicate an error condition.
 
 Non-``200 OK``, non-``404 Not Found`` responses **MAY** include a body which,
 if present, **MUST** be a JSON object containing an
-`Error Response`_.
+`Error Response <Error Responses>`_.
 
 .. _token-exchange:
 
 Trusted Publishing Token Exchange
 ---------------------------------
 
-Once an uploading client has performed a successful :ref:`discovery <discovery>`
-flow, it can proceed to perform the actual Trusted Publishing token exchange.
+Once an uploading client has performed a successful
+`discovery <Trusted Publishing Discovery>`__ flow, it can proceed to perform
+the actual Trusted Publishing token exchange.
 
 Token exchange occurs in three steps:
 
@@ -199,7 +227,7 @@ Audience Retrieval
 
 To retrieve the expected OIDC audience, the uploading client performs
 an HTTP GET request to the *audience endpoint* obtained during
-:ref:`discovery <discovery>`.
+`discovery <Trusted Publishing Discovery>`__.
 
 On success, the server responds with a ``200 OK`` status code and a body
 containing a JSON object with the following field:
@@ -224,7 +252,7 @@ proceed to mint an upload credential.
 
 To mint an upload credential, the uploading client performs
 an HTTP POST request to the *mint token endpoint* obtained during
-:ref:`discovery <discovery>`.
+`discovery <Trusted Publishing Discovery>`__.
 
 On success, the server responds with a ``200 OK`` status code and a body
 containing a JSON object with the following fields:
@@ -356,7 +384,7 @@ However, this approach also has downsides:
 
 Another alternative idea considered was the perform "implicit" discovery,
 similar to what PyPI currently does for Trusted Publishing: instead of an
-explicit :ref:`discovery <discovery>` step, the uploading client could jump
+explicit `discovery <Trusted Publishing Discovery>`__ step, the uploading client could jump
 straight to attempting the audience and token minting steps, and
 handle any errors that arise.