Skip to content

PEP 694: Amend scanning in staged releases and add legacy API changes to use staged releases #5070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cjames23 wants to merge 7 commits into
base: main
Choose a base branch
from
Open

PEP 694: Amend scanning in staged releases and add legacy API changes to use staged releases #5070

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1469ee8
Add amendments to 694 for scanning in staged releases and add legacy …
cjames23 Aug 3, 2026
f4d9632
Address PR comments
cjames23 Aug 8, 2026
fab9c5e
Merge branch 'main' into pep-694-staged-releases-legacy-entry
warsaw Aug 19, 2026
75a4595
Address comments by adding more clarity on not mixing the two paths b…
cjames23 Sep 8, 2026
caacbed
Merge branch 'main' into pep-694-staged-releases-legacy-entry
cjames23 Sep 8, 2026
3562b92
Merge branch 'main' into pep-694-staged-releases-legacy-entry
cjames23 Sep 28, 2026
679169d
Address comments for stronger wording including section on avoiding d…
cjames23 Oct 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Address comments by adding more clarity on not mixing the two paths b… 
…etween legacy and 2.0, minor fixes for other sections.
  • Loading branch information
@cjames23
cjames23 committed Sep 8, 2026
commit 75a4595671b484318fc941036d82cb2e428375c2
24 changes: 18 additions & 6 deletions peps/pep-0694.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Along with standardization, the upload API provides additional useful features s
without the need for `test.pypi.org <https://test.pypi.org/>`__;

* entering the publishing session workflow from the existing legacy upload API, so that staging is
available to publishers before their tooling adopts this API;
available to publishers before their tooling fully adopts this API;

* artifacts which can be overwritten and replaced, until a session is published;

Expand Down Expand Up @@ -614,8 +614,8 @@ Create a Publishing Session from a Legacy Upload
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Publishers cannot use the features of this API until their upload tooling adopts it, and the legacy API is
expected to remain available as this pep does not propose a deprecatioin schedule. To make staging available to those publishers sooner, an index
**MAY** allow a legacy upload to create a publishing session, so that from creation onward the session is the
expected to remain available anyway, as this PEP does not propose a deprecation schedule. To make staging available to those publishers sooner,
an index **MAY** allow a legacy upload to create a publishing session, so that from creation onward the session is the
same as one created directly.

An index that supports this **MUST** document it, and **SHOULD** accept a ``staged`` field with the value
Expand All @@ -627,19 +627,31 @@ including the ``links`` and ``session-token`` keys, so that the publisher can th
PEP to :ref:`preview <staged-preview>`, :ref:`publish <publishing-session-completion>`, or :ref:`cancel
<publishing-session-cancellation>` the session. An index **MAY** also create a session for an upload based on

@ewdurbin ewdurbin Sep 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One concern here: Indexes which return the new publishing session creation response body to a client that does not understand it may end up in situations where the client then logs that response body to their logs (I'm thinking in public CI).

I don't think these need to be treated as strictly sensitive as the expectation of a tool that does not know what to do with the result is that the file is immediately visible on PyPI, but I wanted to flag it.

its own policy or the project's configuration, without the field being present; this allows a project to
require that its releases are staged in a way that an upload client cannot bypass.
require that its releases are staged in a way that an upload client cannot bypass. In this policy driven
case no client change is required at all; the ``staged`` field lets a publisher opt in per upload with only a
minimal change to existing tooling.

Because the legacy API uploads a single file per request, subsequent legacy uploads for the same project and
Comment thread
cjames23 marked this conversation as resolved.
version **SHOULD** be added to the same open session when that session was itself created through a legacy
upload, so that the release is still published as a unit.

A session's creation path is fixed when it is created, and the two paths are not mixed. If a non-terminal
session already exists for a name-version pair (see :ref:`publishing-session-multiple`), a request to
A session's creation path is fixed when it is created, and the two paths **MUST NOT** be mixed.
If a non-terminal session already exists for a name-version pair (see :ref:`publishing-session-multiple`), a request to
contribute to it through the *other* path **MUST** be rejected with a ``409 Conflict``: a legacy
``staged=true`` upload for a pair that already has an open session created through the Upload 2.0 API is
rejected, and an Upload 2.0 request that would add to a session created through a legacy upload is likewise
rejected.
Comment thread
cjames23 marked this conversation as resolved.
Outdated

Fixing the path at creation avoids ambiguity in how the session reaches a terminal state. An Upload 2.0
session is driven to completion by a client that holds its ``session-token`` and calls the control plane
endpoints, whereas a legacy created session is completed by continued legacy uploads and by the index acting
on the publisher's behalf. Allowing a legacy ``staged=true`` upload to join an existing Upload
2.0 session would mean issuing a ``session-token`` for, and granting completion authority over, a session the
legacy uploader did not create; allowing an Upload 2.0 request to add to a legacy created session would
subject a legacy publisher to a completion model its tooling does not implement. Rejecting cross path
contribution keeps the authority to publish or cancel a session with the path that created it, which also
keeps any :ref:`separate publishing authorization <authentication>` on that session unambiguous.

A legacy client that is unaware of this PEP cannot issue a :ref:`publish request
<publishing-session-completion>`. Where an index has created a session on such a client's behalf, and the
session is subject only to automated processing, the index **MAY** publish the session itself once that

@ewdurbin ewdurbin Sep 29, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the scenario where an index uses sessions by policy of the index/project, it seems this leaves clients who do not support the new protocol in bit of a lurch, unable to control when their staged files enter the processing state which may be before they want, or long after.

I assume there is some desire for this to eventually be the default on PyPI to provide a mechanism for pre-publication malware scanning, so I think it is a bit unwieldy to not have a story around how we will handle users of legacy clients who may never adopt explicit session support.

If I'm honest, I would prefer that we move very quickly to rollout Upload 2.0, and then very quickly to deprecate the legacy endpoint, as active uploaders are the some of the most easily "reached" clients we have. When their publication flows break, they are much more likely to be actively ready to repair them.

I'm a bit concerned that having the interop period, with itself potentially being divided between "opt-in" and "by policy" staging, creating more than one distinct migration/adoption period.

@cjames23 cjames23 Oct 3, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to agree I would definitely like the rollout of Upload 2.0 and deprecation of the legacy endpoint to be quick in succession. I think otherwise places a lot of burden on maintenance and as you stated it can create more than one adoption period. And speaking from JOB1 experience the longer that a migration is allowed to take the longer that the long tail becomes.

Expand Down
Loading