PEP 592: Support for "Yanked" Files on the Simple API (#1032)

pep-0592.rst

@@ -0,0 +1,93 @@
+PEP: 592
+Title: Adding "Yank" Support to the Simple API
+Author: Donald Stufft <donald@stufft.io>
+BDFL-Delegate: Donald Stufft <donald@stufft.io>
+Discussions-To: https://discuss.python.org/c/packaging
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 07-May-2019
+Post-History:
+
+
+Abstract
+========
+
+This PEP proposes adding the ability to mark a particular file download
+on a simple repository as "yanked". Yanking a file allows authors to
+effectively delete a file, without breaking things for people who have
+pinned to exactly a specific version.
+
+It also changes to the canonical source for the simple repository API to
+the `Simple Repository API`_ reference document.
+
+
+Motivation
+==========
+
+Whenever a project detects that a particular release on PyPI might be
+broken, they often times will want to prevent further users from
+inadvertantly using that version. However, the obvious solution of
+deleting the existing file from a repository will break users who have
+followed best practices and pinned to a specific version of the project.
+
+This leaves projects in a catch-22 situation where new projects may be
+pulling down this known broken version, but if they do anything to
+prevent that they'll break projects that are already using it.
+
+By allowing the ability to "yank" a file, but still make it available
+for users who are explicitly asking for it, this allows projects to
+mitigate the worst of the breakage while still keeping things working
+for projects who have otherwise worked around or didn't hit the
+underlying issues.
+
+
+Specification
+=============
+
+Links on the simple repository **MAY** have a ``data-yanked`` attribute
+which can be either a ``true``, ``false``, or have no value at all. For
+the purposes of this PEP, having no value is interpretted as a ``true``
+value.
+
+When an installer encounters a link that has a true ``data-yanked``
+attribute, they **SHOULD** treat that file link as if it does not
+exist *UNLESS* the user is requesting the version of that file using
+an exact ``==`` match. In other words, ``foo==1.0`` should install
+a yanked 1.0, but ``foo>0``, ``foo``, ``foo==1.*``, etc should not.
+
+In addition, and installer **SHOULD** only use a yanked file as a last
+resort if there are no files available that match the requested
+version that are not yanked.
+
+
+Rejected Ideas
+==============
+
+A previous, undocumented, version of the simple repository API had
+version specific pages, like ``/simple/<project>/<version>/``. If
+we were to add those back, the yanked files could only appear on
+those pages and not on the version-less page at all.
+
+However this would drastically reduce the cache-ability of the simple
+API and would directly impact our ability to scale it out to handle
+all of the incoming traffic.
+
+
+.. _`Simple Repository API`:
+   https://packaging.python.org/specifications/simple-repository-api/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.
+
+..
+   Local Variables:
+   mode: indented-text
+   indent-tabs-mode: nil
+   sentence-end-double-space: t
+   fill-column: 70
+   coding: utf-8
+   End: