PEP 621: data specified is canonical (#1651)

pep-0621.rst

@@ -34,6 +34,7 @@ The key motivators of this PEP are:
   learning and transitioning between build back-ends
 - Allow for more code sharing between build back-ends for the
   "boring parts" of a project's metadata
+- Provide a way to specify canonical data
 
 This PEP does **not** attempt to standardize all possible metadata
 required by a build back-end, only the metadata covered by the
@@ -49,15 +50,6 @@ This PEP is also not trying to change the underlying `core metadata`_
 in any way. Such considerations should be done in a separate PEP which
 may lead to changes or additions to what this PEP specifies.
 
-Finally, this PEP is meant for users to specify metadata for build
-back-ends or those doing analysis on a source checkout. Once a build
-back-end has produced an artifact, then the metadata
-contained in the artifact that the build back-end produced should be
-considered canonical and overriding what this PEP specifies. In the
-eyes of this PEP, a source distribution is considered a build
-artifact, thus people should not read the metadata specified in this
-PEP as the canonical metadata in a source distribution.
-
 
 Rationale
 =========
@@ -66,19 +58,17 @@ The design guidelines the authors of this PEP followed were:
 
 - Define as much of the `core metadata`_ as reasonable
 - Define the metadata statically with an escape hatch for those who
-  want to define it dynamically
+  want to define it dynamically later
 - Use familiar names where it makes sense, but be willing to use more
   modern terminology
 - Try to be ergonomic within a TOML file instead of mirroring how
-  tools specify metadata at a low-level
+  tools specify metadata at a low-level when it makes sense
 - Learn from other build back-ends in the packaging ecosystem which
   have used TOML for their metadata
 - Don't try to standardize things which lack a pre-existing standard
   at a lower-level
-- *When* metadata is specified using this PEP then it is considered
-  canonical, but that any and all metadata can be considered
-  *optional* (`core metadata`_ has its own requirements of what
-  data must be provided *somehow*)
+- *When* metadata is specified using this PEP, it is considered
+  canonical
 
 
 Specification
@@ -88,6 +78,11 @@ When specifying project metadata, tools MUST adhere and honour the
 metadata as specified in this PEP. If metadata is improperly specified
 then tools MUST raise an error to notify the user about their mistake.
 
+Data specified using this PEP is considered canonical. Tools CANNOT
+remove or change data, but they MAY add to it. This allows for tools
+to make data more accurate/static when possible by updating the data
+specified in the ``pyproject.toml`` file.
+
 Details
 -------
 
@@ -96,10 +91,11 @@ Table name
 
 Tools MUST specify fields defined by this PEP in a table named
 ``[project]``. No tools may add fields to this table which are not
-defined by this PEP. For tools wishing to store their own settings in
-``pyproject.toml``, they may use the ``[tool]`` table as defined in
-:pep:`518`. The lack of a ``[project]`` table implicitly means the
-build back-end will dynamically provide all fields.
+defined by this PEP or subsequent PEPs. For tools wishing to store
+their own settings in ``pyproject.toml``, they may use the ``[tool]``
+table as defined in :pep:`518`. The lack of a ``[project]`` table
+implicitly means the build back-end will dynamically provide all
+fields.
 
 ``name``
 ''''''''
@@ -173,7 +169,7 @@ The full description of the project (i.e. the README).
 
 The field accepts either a string or a table. If it is a string then
 it is the relative path to a text file containing the full
-description. Tools MUST assume the file's encoding as UTF-8. If the
+description. Tools MUST assume the file's encoding is UTF-8. If the
 file path ends in a case-insensitive ``.md`` suffix, then tools MUST
 assume the content-type is ``text/markdown``. If the file path ends in
 a case-insensitive ``.rst``, then tools MUST assume the content-type
@@ -188,14 +184,15 @@ full description. The ``text`` key has a string value which is the
 full description. These keys are mutually-exclusive, thus tools MUST
 raise an error if the metadata specifies both keys.
 
-The table also has a ``content-type`` field which takes a string
-specifying the content-type of the full description. A tool MUST raise
-an error if the metadata does not specify this field in the table. If
-the metadata does not specify the ``charset`` parameter, then it is
-assumed to be UTF-8. Tools MAY support other encodings if they choose
-to. Tools MAY support alternative content-types which they can
-transform to a content-type as supported by the `core metadata`_.
-Otherwise tools MUST raise an error for unsupported content-types.
+A table specified in the ``readme`` field also has a ``content-type``
+field which takes a string specifying the content-type of the full
+description. A tool MUST raise an error if the metadata does not
+specify this field in the table. If the metadata does not specify the
+``charset`` parameter, then it is assumed to be UTF-8. Tools MAY
+support other encodings if they choose to. Tools MAY support
+alternative content-types which they can transform to a content-type
+as supported by the `core metadata`_. Otherwise tools MUST raise an
+error for unsupported content-types.
 
 ``requires-python``
 '''''''''''''''''''
@@ -355,12 +352,13 @@ Entry points
     (`link <https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata>`__)
 
 There are three tables related to entry points. The
-``[project.scripts]`` table corresponds to ``console_scripts`` group.
-The key of the table is the name of the entry point and the value is
-the object reference.
+``[project.scripts]`` table corresponds to the ``console_scripts``
+group in the `core metadata`_. The key of the table is the name of the
+entry point and the value is the object reference.
 
 The ``[project.gui-scripts]`` table corresponds to the ``gui_scripts``
-group. Its format is the same as ``[project.scripts]``.
+group in the `core metadata`_. Its format is the same as
+``[project.scripts]``.
 
 The ``[project.entry-points]`` table is a collection of tables. Each
 sub-table's name is an entry point group. The key and value semantics
@@ -427,8 +425,9 @@ provided via tooling later on.
   ``name`` in ``dynamic``.
 - If the `core metadata`_ specification lists a field as "Required",
   then the metadata MUST specify the field statically or list it in
-  ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. a
-  required field is in no way listed in a ``pyproject.toml`` file).
+  ``dynamic`` (build back-ends MUST raise an error otherwise, i.e. it
+  should not be possible for a required field to not be listed somehow
+  in the ``[project]`` table).
 - If the `core metadata`_ specification lists a field as "Optional",
   the metadata MAY list it in ``dynamic`` if the expectation is a
   build back-end will provide the data for the field later.
@@ -507,9 +506,9 @@ outlined in :pep:`518`, there are no backwards-compatibility concerns.
 Security Implications
 =====================
 
-There are no direct security concerns as this PEP covers how to statically
-define project metadata. Any security issues would stem from how tools
-consume the metadata and choose to act upon it.
+There are no direct security concerns as this PEP covers how to
+statically define project metadata. Any security issues would stem
+from how tools consume the metadata and choose to act upon it.
 
 
 How to Teach This
@@ -521,7 +520,8 @@ How to Teach This
 Reference Implementation
 ========================
 
-There are currently no proofs-of-concept from any build tools implementing this PEP.
+There are currently no proofs-of-concept from any build tools
+implementing this PEP.
 
 
 Rejected Ideas