Rename new table to 'dist-info.files'

peps/pep-0770.rst

@@ -154,7 +154,7 @@ not guaranteed that tools won't break on new metadata versions and fields.
 
 To avoid this delay, simplify overall how to include SBOMs, and to give
 flexibility to build backends and tools, this PEP proposes a new top-level table
-in ``pyproject.toml``, ``[additional-files]``, to safely add data to a Python
+in ``pyproject.toml``, ``[dist-info.files]``, to safely add data to a Python
 package through a registry of reserved names that
 avoids the need for new metadata fields and versions.  This mechanism allows
 build backends and tools to begin using the features described in this PEP
@@ -165,6 +165,30 @@ A new top-level table was chosen over using the ``[project]`` table because,
 as described in :pep:`621`, the ``[project]`` table is used for storing core
 metadata and this mechanism doesn't use core metadata.
 
+Storing files in the ``.dist-info`` or ``.data`` directory
+----------------------------------------------------------
+
+There are two top-level directories in binary distributions where files beyond
+the software itself can be stored: ``.dist-info`` and ``.data``.
+This specification chose to use the ``.dist-info`` directory for storing
+subdirectories and files from the new ``[dist-info.files]`` top-level table
+for two reasons:
+
+Firstly, the ``.data`` directory has no corresponding location in the installed
+package, compared to ``.dist-info`` which does preserve the link between the
+binary distribution to the installed package in an environment. The ``.data``
+directory instead has all its contents merged between all installed packages in
+an environment which can lead to collisions between similarly named files.
+
+Secondly, subdirectories under the ``.data`` directory require new definitions
+to the Python `sysconfig <https://docs.python.org/3/library/sysconfig.html>`__
+module. This means defining additional directories require waiting for a change
+to Python and *using* the directory requires waiting for adoption of the new
+Python version by users. Subdirectories under ``.dist-info`` don't have these
+requirements, they can be used by any user, build backend, and installer
+immediately after a new subdirectory name is registered regardless of Python
+or metadata version.
+
 What are the differences between PEP 770 and PEP 725?
 -----------------------------------------------------
 
@@ -209,9 +233,9 @@ The changes necessary to implement this PEP include:
 
 * Explicitly reserving all subdirectory names in the ``.dist-info`` directory.
 * A new registry of reserved subdirectory names in the ``.dist-info`` directory.
-* An optional top-level table, ``[additional-files]``, added to
+* An optional top-level table, ``[dist-info.files]``, added to
   `project source metadata <770-spec-project-source-metadata_>`_,
-* An optional ``sboms`` key in the new ``[additional-files]`` table,
+* An optional ``sboms`` key in the new ``[dist-info.files]`` table,
 * `Additions <770-spec-project-formats_>`_ to the built distribution (wheel),
   and installed project specifications
 
@@ -264,12 +288,12 @@ Project source metadata
 This PEP specifies changes to the project's source metadata
 in the ``pyproject.toml`` file:
 
-Add new ``[additional-files]`` table
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add new ``[dist-info.files]`` table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A new optional ``[additional-files]`` table is added for specifying paths
+A new optional ``[dist-info.files]`` table is added for specifying paths
 in the project source tree relative to ``pyproject.toml`` to file(s) which
-should be included in the built project to a defined directory.
+should be included in the built project to a subdirectory of ``.dist-info``.
 
 This new table has only one defined optional key: ``sboms``. The value of the
 ``sboms`` key MUST be an array of valid glob patterns, as specified below:
@@ -308,31 +332,31 @@ Examples of valid SBOM files declarations:
 
 .. code-block:: toml
 
-    [additional-files]
+    [dist-info.files]
     sboms = ["bom.json"]
 
-    [additional-files]
+    [dist-info.files]
     sboms = ["sboms/openssl.cdx.json", "sboms/openssl.spdx.json"]
 
-    [additional-files]
+    [dist-info.files]
     sboms = ["sboms/*"]
 
-    [additional-files]
+    [dist-info.files]
     sboms = []
 
 Examples of invalid SBOM files declarations:
 
 .. code-block:: toml
 
-    [additional-files]
+    [dist-info.files]
     sboms = ["..\bom.json"]
 
 Reason: ``..`` must not be used. ``\\`` is an invalid path delimiter, ``/``
 must be used.
 
 .. code-block:: toml
 
-    [additional-files]
+    [dist-info.files]
     sboms = ["bom{.json*"]
 
 Reason: ``bom{.json*`` is not a valid glob.
@@ -347,11 +371,10 @@ A few additions will be made to the existing specifications.
 :term:`Project source trees <Project source tree>`
   Per :ref:`770-spec-project-source-metadata` section, the
   `Declaring Project Metadata specification <pyprojecttoml_>`__
-  will be updated to add the ``[additional-files]`` table
+  will be updated to add the ``[dist-info.files]`` table
   and optional ``sboms`` key.
 
 :term:`Built distributions <Built distribution>` (:term:`wheels <wheel>`)
-
   The wheel specification will be updated to add the new registry of reserved
   directory names and to reflect that if the ``.dist-info/sboms`` subdirectory
   is specified that the directory contains SBOM files.
@@ -504,7 +527,7 @@ and then include those files using ``pyproject.toml``:
 
 .. code-block:: toml
 
-    [additional-files]
+    [dist-info.files]
     sboms = [
        "sboms/bom.cdx.json"
     ]
@@ -622,7 +645,7 @@ are almost always static.
 
 The 639-style approach was ultimately dropped in favor of defining SBOMs simply
 by their presence in the ``.dist-info/sboms`` directory and using a new table in
-``pyproject.toml`` called ``[additional-files]`` to define SBOMs in source
+``pyproject.toml`` called ``[dist-info.files]`` to define SBOMs in source
 distributions. This approach allows users to specify static SBOM files while
 still empowering build backends and tools to add their own SBOM data without the
 static/dynamic conflict.
@@ -664,7 +687,7 @@ Acknowledgements
 
 Thanks to Karolina Surma for authoring and leading :pep:`639` to acceptance.
 This PEP's initial design was heavily inspired by :pep:`639` and the new
-"additional files" mechanism generalizes 639's approach of using a subdirectory
+"dist-info.files" mechanism generalizes 639's approach of using a subdirectory
 under ``.dist-info``.
 
 Copyright