PEP 708: Allow tracking multiple repositories and rewording (#3162)

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 <packaging: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 <https://pypi.org/project/bandersnatch/>`__) or when a repository
 is providing supplementary artifacts for a specific platform (see
 `Piwheels <https://www.piwheels.org/>`__).
 
-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
       <head>
         <meta name="pypi:repository-version" content="1.2">
         <meta name="pypi:tracks" content="https://pypi.org/simple/holygrail/">
+        <meta name="pypi:tracks" content="https://test.pypi.org/simple/holygrail/">
       </head>
       <body>
         <a href="https://example.com/files/holygrail-1.0.tar.gz#sha256=...">