PEP 792: additional review feedback (#4463)

woodruffw · web-flow · commit a0d84ceb2a0c · 2025-06-16T18:20:57.000+03:00
diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst
@@ -108,7 +108,7 @@ A project always has exactly one status. If no status is explicitly noted,
 then the project is considered to be in the ``active`` state.
 
 Indices **MAY** implement any subset of the status markers specified in this
-PEP, as applicable.
+PEP, as applicable to their needs.
 
 This PEP does not prescribe *which* principals (i.e. project maintainers,
 index administrators, etc.) are allowed to set and unset which statuses.
@@ -189,10 +189,14 @@ HTML index
 The following changes are made to the
 :ref:`simple repository API <packaging:simple-repository-api-base>`:
 
-* The per-project index **SHALL** define the ``pypi:repository-version`` as ``1.4``.
+* The per-project index **MUST** define the ``pypi:repository-version`` as ``1.4``.
 * The per-project index **SHOULD** add an appropriate ``pypi:project-status`` meta tag, with
   a ``content`` of the project's status marker. The index **MAY** choose to omit
   the ``pypi:project-status`` meta tag if the project is marked as ``active``.
+* The per-project index **MAY** include a ``pypi:project-status-reason`` meta tag,
+  with a ``content`` of free-form text contextualizing the project's status.
+  The index **MAY** choose to omit the ``pypi:project-status-reason`` meta tag
+  if the project is marked as ``active`` or if no reason is provided.
 
 For example, the following would be a valid HTML index response for
 ``sampleproject`` after is has been marked as ``quarantined``:
@@ -205,6 +209,7 @@ For example, the following would be a valid HTML index response for
       <head>
         <meta name="pypi:repository-version" content="1.4">
         <meta name="pypi:project-status" content="quarantined">
+        <meta name="pypi:project-status-reason" content="the project is haunted">
         <title>Links for sampleproject</title>
       </head>
       <body>
@@ -221,10 +226,14 @@ JSON index
 The following changes are made to the
 :ref:`JSON simple index <packaging:simple-repository-api-json>`:
 
-* The per-project index **SHALL** define the ``meta.api-version`` as ``1.4``.
-* The per-project index **SHOULD** include a ``project-status`` key in the JSON response,
+* The per-project index **MUST** define the ``meta.api-version`` as ``1.4``.
+* The per-project index **SHOULD** include a ``project-status.state`` key in the JSON response,
   with a value of the project's status marker. The index **MAY** choose to omit
-  the ``project-status`` key if the project is marked as ``active``.
+  the ``project-status.state`` key if the project is marked as ``active``.
+* The per-project index **MAY** include a ``project-status.reason`` key in the JSON response,
+  with a value of free-form text contextualizing the project's status.
+  The index **MAY** choose to omit the ``project-status.reason`` key
+  if the project is marked as ``active`` or if no reason is provided.
 
 For example, the following would be a valid JSON index response for
 ``sampleproject`` after is has been marked as ``quarantined``:
@@ -236,7 +245,10 @@ For example, the following would be a valid JSON index response for
       "meta": {
         "api-version": "1.4"
       },
-      "project-status": "quarantined",
+      "project-status": {
+        "status": "quarantined",
+        "reason": "the project is haunted"
+      },
       "alternate-locations": [],
       "files": [],
       "name": "sampleproject",
