PEP 621: Clarify expectations for sdists (#1652)

pep-0621.rst

@@ -28,13 +28,14 @@ Motivation
 The key motivators of this PEP are:
 
 - Encourage users to specify core metadata statically for speed,
-  ease of specification, deterministic consumption by build back-ends,
-  and ease analysis of source checkouts
+  ease of specification, and deterministic consumption by build
+  back-ends
 - Provide a tool-agnostic way of specifying the metadata for ease of
   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
+- Provide a way to specify canonical data both by users and in
+  source distributions
 
 This PEP does **not** attempt to standardize all possible metadata
 required by a build back-end, only the metadata covered by the
@@ -69,6 +70,9 @@ The design guidelines the authors of this PEP followed were:
   at a lower-level
 - *When* metadata is specified using this PEP, it is considered
   canonical
+- Make the specified data useful in a source distribution to
+  statically define what metadata is known at the time of source
+  distribution creation
 
 
 Specification
@@ -81,7 +85,19 @@ 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.
+specified in the ``pyproject.toml`` file. For example, a version
+can become more specific when building a wheel (e.g. adding a local
+version), but it cannot become less specific.
+
+Build back-ends creating a source distribution -- aka an "sdist" --
+SHOULD provide as much data as possible using this PEP within a source
+distribution. The ``name`` and ``version`` fields MUST NOT be omitted
+and must be statically specified. Other fields which pertain to data
+surfaced on PyPI, and thus are not expected to be determined at wheel
+creation time, MUST NOT be listed as ``dynamic`` in a source
+distribution. All other fields have no specific requirements placed
+upon them in a source distribution.
+
 
 Details
 -------
@@ -102,6 +118,7 @@ fields.
 - Format: string
 - `Core metadata`_: ``Name``
   (`link <https://packaging.python.org/specifications/core-metadata/#name>`__)
+- Source distributions: required
 - Synonyms
 
   - Flit_: ``module``/``dist-name``
@@ -123,6 +140,7 @@ as it is read for internal consistency.
 - Format: string
 - `Core metadata`_: ``Version``
   (`link <https://packaging.python.org/specifications/core-metadata/#version>`__)
+- Source distributions: required
 - Synonyms
 
   - Flit_: N/A (read from a ``__version__`` attribute)
@@ -141,6 +159,7 @@ Users SHOULD prefer to specify already-normalized versions.
 - Format: string
 - `Core metadata`_: ``Summary``
   (`link <https://packaging.python.org/specifications/core-metadata/#summary>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: N/A
@@ -156,6 +175,7 @@ The summary description of the project.
 - Format: String or table
 - `Core metadata`_: ``Description``
   (`link <https://packaging.python.org/specifications/core-metadata/#description>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``description-file``
@@ -199,6 +219,7 @@ error for unsupported content-types.
 - Format: string
 - `Core metadata`_: ``Requires-Python``
   (`link <https://packaging.python.org/specifications/core-metadata/#summary>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``requires-python``
@@ -220,6 +241,7 @@ the user specified for this field.
 - Format: Table
 - `Core metadata`_: ``License``
   (`link <https://packaging.python.org/specifications/core-metadata/#license>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``license``
@@ -249,6 +271,7 @@ classifiers.
 - Format: Array of inline tables with string keys and values
 - `Core metadata`_: ``Author``/``Author-email``/``Maintainer``/``Maintainer-email``
   (`link <https://packaging.python.org/specifications/core-metadata/#author>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``author``/``author-email``/``maintainer``/``maintainer-email``
@@ -288,6 +311,7 @@ Using the data to fill in `core metadata`_ is as follows:
 - Format: array of strings
 - `Core metadata`_: ``Keywords``
   (`link <https://packaging.python.org/specifications/core-metadata/#keywords>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``keywords``
@@ -304,6 +328,7 @@ The keywords for the project.
 - Format: array of strings
 - `Core metadata`_: ``Classifier``
   (`link <https://packaging.python.org/specifications/core-metadata/#classifier-multiple-use>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``classifiers``
@@ -323,6 +348,7 @@ if the back-end can deduce the classifiers from the provided metadata.
 - Format: Table, with keys and values of strings
 - `Core metadata`_: ``Project-URL``
   (`link <https://packaging.python.org/specifications/core-metadata/#project-url-multiple-use>`__)
+- Source distributions: cannot by dynamic
 - Synonyms
 
   - Flit_: ``[tool.flit.metadata.urls]`` table
@@ -341,6 +367,7 @@ Entry points
   ``[project.entry-points]``)
 - `Core metadata`_: N/A;
   `Entry point specification <https://packaging.python.org/specifications/entry-points/>`_
+- Source distributions: optional
 - Synonyms
 
   - Flit_: ``[tool.flit.scripts]`` table for console scripts,
@@ -380,6 +407,7 @@ be ambiguous in the face of ``[project.scripts]`` and
 - `Core metadata`_: ``Requires-Dist`` and ``Provides-Extra``
   (`link <https://packaging.python.org/specifications/core-metadata/#requires-dist-multiple-use>`__,
   `link <https://packaging.python.org/specifications/core-metadata/#provides-extra-multiple-use>`__)
+- Source distributions: optional
 - Synonyms
 
   - Flit_: ``requires`` for required dependencies, ``requires-extra``
@@ -411,6 +439,7 @@ thus becomes a corresponding ``Requires-Dist`` entry for the matching
 '''''''''''
 - Format: Array of strings
 - `Core metadata`_: N/A
+- Source distributions: optional
 - No synonyms
 
 Specifies which fields listed by this PEP were intentionally