Last minute cleanups

Author: warsaw

peps/pep-0694.rst

@@ -804,13 +804,13 @@ Indexes advertise their support for staged previews by returning two key pieces
 :ref:`response to publishing session creation <publishing-session-response>`.  Indexes which don't support
 staged previews **MUST NOT** include these in their responses.
 
-The ``session-token`` is a short token which could be used as a convenience for installation tool UX, if they
-want to support staged previews via a command line switch, e.g. ``pip install --staged $SESSION_TOKEN``.  The
-``links.stage`` key gives the full URL to the stage, which could be used in the CLI, e.g. ``pip
-install --extra-index-url $STAGE_URL``.  Both the session token and URL **MUST** be cryptographically
-unguessable, but the algorithm for generating the token is left to the index.  The stage URL **MUST** be
-calculable from the session token, using a format documented by the index, but the exact format of the URL is
-also left to the index.
+The ``session-token`` is a short token which could be used as a convenience for installation tool UX.  For
+example, ``pip`` could add a ``--stage $SESSION_TOKEN`` flag as a convenience for installing from a staged
+preview.  The ``links.stage`` key gives the full URL to the stage, which can be used with installers today,
+e.g. ``pip install --extra-index-url $STAGE_URL``.  Both the session token and URL **MUST** be
+cryptographically unguessable, but the algorithm for generating the token is left to the index.  The stage URL
+**MUST** be calculable from the session token, using a format documented by the index, but the exact format of
+the URL is also left to the index.
 
 
 File Upload Session
@@ -1390,13 +1390,13 @@ command.  The Upload 2.0 protocol could be exposed through additional options:
     commands.  This session identifier is local to the client and is mapped internally to the
     in-progress server session.
 
-``twine publish <session-id>``
+``twine session publish <session-id>``
     Publishes a previously staged session.
 
-``twine cancel <session-id>``
+``twine session cancel <session-id>``
     Cancels a staged session and discards all uploaded files.
 
-``twine status <session-id>``
+``twine session status <session-id>``
     Queries and displays the current status of a session.
 
 uv
@@ -1410,12 +1410,22 @@ uv
 
 ``uv publish --stage dist/*``
     Uploads without publishing.  Like twine, this is valuable even without stage preview support.
+    Prints a session identifier that can be used with the ``uv session`` subcommands.
 
 ``uv publish --test-install dist/*``
     If the index supports stage previews, uploads files, installs the package from the stage URL
     into a temporary virtual environment, optionally runs a smoke test command, and only publishes
     if successful.  This provides an integrated "upload, test, publish" workflow.
 
+``uv session publish <session-id>``
+    Publishes a previously staged session.
+
+``uv session cancel <session-id>``
+    Cancels a staged session and discards all uploaded files.
+
+``uv session status <session-id>``
+    Queries and displays the current status of a session.
+
 GitHub Actions
 ~~~~~~~~~~~~~~
 
@@ -1438,7 +1448,7 @@ leverage staged releases to enable powerful CI/CD workflows.  A multi-job workfl
           - id: upload
             uses: pypa/gh-action-pypi-publish@v2
             with:
-              stage-only: true  # Upload but don't publish
+              stage: true  # Upload but don't publish
 
       test:
         needs: upload
@@ -1715,21 +1725,25 @@ Change History
     publishers contributing to one session, and notes the related security implications.
   * Remove the optional ``metadata`` key from the file upload session creation request.  The uploaded file is
     the authoritative source of metadata, which the index extracts from the file itself.
-  * Define an explicit publishing-session state machine.  Rename the session-level ``pending`` status to
-    ``open``, add a transitional ``processing`` status for deferred (``202 Accepted``) publishing, and document
-    the ``error`` status as a still-editable state that records a failed deferred publish (with the reason
-    reported in ``notices``).  Add a **Publishing Session States** section with state descriptions and a
-    transition table, specify that a synchronous publish failure leaves the session editable rather than
-    entering ``error``, and require the server to reject cancellation with a ``409 Conflict`` while a session is
-    ``processing``.  Key the **Multiple Session Creation Requests** rule off any non-terminal state rather than
-    ``pending``.
-  * Document the file upload session state machine with a **File Upload Session States** section and transition
-    table.  Specify that any completion failure -- synchronous or deferred -- moves the session to ``error``,
-    that an ``error`` file cannot be repaired in place (the client cancels or deletes it and starts a new file
-    upload session), and that the server **MUST** reject a ``DELETE`` with a ``409 Conflict`` while a session
-    is ``processing``.
+  * Define an explicit publishing-session state machine.  Rename the session-level ``pending``
+    status to ``open``, add a transitional ``processing`` status for deferred (``202 Accepted``)
+    publishing, and document the ``error`` status as a still-editable state that records a failed
+    deferred publish (with the reason reported in ``notices``).  Add a **Publishing Session States**
+    section with state descriptions and a transition table, specify that a synchronous publish
+    failure leaves the session editable rather than entering ``error``, and require the server to
+    reject cancellation with a ``409 Conflict`` while a session is ``processing``.  Key the
+    **Multiple Session Creation Requests** rule off any non-terminal state rather than ``pending``.
+  * Document the file upload session state machine with a **File Upload Session States** section and
+    transition table.  Specify that any completion failure -- synchronous or deferred -- moves the
+    session to ``error``, that an ``error`` file cannot be repaired in place (the client cancels or
+    deletes it and starts a new file upload session), and that the server **MUST** reject a
+    ``DELETE`` with a ``409 Conflict`` while a session is ``processing``.
   * Add state transition diagrams to the **Publishing Session States** and **File Upload Session States**
     sections, alongside the existing transition tables.
+  * Make the suggested ``twine`` and ``uv`` command-line interfaces consistent: group the staged-session
+    operations under a ``session`` subcommand (``session publish``/``session cancel``/``session status``),
+    give ``uv`` the same staged-session follow-ups and session-id output as ``twine``, and align the GitHub
+    Action's ``stage`` input with the ``--stage`` flag.
 
 * `07-Dec-2025 <https://discuss.python.org/t/pep-694-pypi-upload-api-2-0-round-2/101483/35>`__
 
@@ -1744,7 +1758,8 @@ Change History
   * Clarify publishing session steps such as status polling and session extension.
   * Require that ``name`` conform to the normalization rules, and include a link.
   * Require that ``version`` conform to the version specs, and include a link.
-  * Require ``filename`` to conform to either the source or binary distribution file name convention, and include links.
+  * Require ``filename`` to conform to either the source or binary distribution file name convention, and
+    include links.
   * Reference RFC 3399 instead of ISO 8601 as the timestamp spec. The RFC is a simpler format that
     subsets the ISO standard, and is more appropriate to our use case.
   * Other protocol clarifications.