diff --git a/pep-0708.rst b/pep-0708.rst index 4b8298799..abe37d608 100644 --- a/pep-0708.rst +++ b/pep-0708.rst @@ -26,7 +26,7 @@ from one repository (e.g. a custom index) is installed from another (e.g. PyPI). To help address this problem, this PEP proposes extending the :ref:`Simple Repository API ` to allow repository operators to indicate that a project found on their -repository "tracks" a project on a different repository, and allows projects to +repository "tracks" a project on different repositories, and allows projects to extend their namespaces across multiple repositories. These features will allow installers to determine when a project being made @@ -105,13 +105,13 @@ There are two broad use cases for merging names across repositories that this PEP seeks to enable. The first use case is when one repository is not defining its own names, but -rather is extending names defined in another repository. This commonly happens +rather is extending names defined in other repositories. This commonly happens in cases where a project is being mirrored from one repository to another (see `Bandersnatch `__) or when a repository is providing supplementary artifacts for a specific platform (see `Piwheels `__). -In this case neither the repository nor the projects that are being extended +In this case neither the repositories nor the projects that are being extended may have any knowledge that they are being extended or by whom, so this cannot rely on any information that isn't present in the "extending" repository itself. @@ -160,10 +160,15 @@ Locations". Repository "Tracks" Metadata ---------------------------- -To enable one repository to extend another, this PEP allows the extending -repository to declare that it "tracks" another repository by adding the URL -of the repository that it is extending. This is exposed in JSON as the key -``meta.tracks`` and in HTML as a meta element named ``pypi:tracks``. +To enable one repository to host a project that is intended to "extend" a +project that is hosted at other repositories, this PEP allows the extending +repository to declare that a particular project "tracks" a project at another +repository or repositories by adding the URLs of the project and repositories +that it is extending. + +This is exposed in JSON as the key ``meta.tracks`` and in HTML as a meta element +named ``pypi:tracks``. + There are a few key properties that **MUST** be preserved when using this metadata: @@ -176,21 +181,22 @@ metadata: like hosted repository services where one entity operates the software but another owns/manages the entire namespace of that repository. -- It **MUST** represent the same "project" as the project at the referenced URL. +- All URLs **MUST** represent the same "project" as the project at in the + extending repository. - - This does not mean that it needs to serve the same files. It is valid for it + - This does not mean that they need to serve the same files. It is valid for it to include binaries built on different platforms, copies with local patches being applied, etc. This is purposefully left vague as it's ultimately up to the expectations that the users have of the repository and its operators what exactly constitutes the "same" project. -- It **MUST** point to the repository that "owns" the namespace, not another +- It **MUST** point to the repositories that "owns" the namespaces, not another repository that is also tracking that namespace. - It **MUST** point to a project with the exact same name (after normalization). -- It **MUST** point to the actual URL for that project, not the base URL for the - extended repository. +- It **MUST** point to the actual URLs for that project, not the base URL for + the extended repositories. It is **NOT** required that every name in a repository tracks the same repository, or that they all track a repository at all. Mixed use repositories @@ -206,7 +212,7 @@ JSON { "meta": { "api-version": "1.2", - "tracks": "https://pypi.org/simple/holygrail/" + "tracks": ["https://pypi.org/simple/holygrail/", "https://test.pypi.org/simple/holygrail/"] }, "name": "holygrail", "files": [ @@ -238,6 +244,7 @@ HTML +