PEP 621: address feedback (#1701)

pep-0621.rst

@@ -14,7 +14,8 @@ Content-Type: text/x-rst
 Created: 22-Jun-2020
 Post-History: 22-Jun-2020,
               18-Oct-2020,
-              24-Oct-2020
+              24-Oct-2020,
+              31-Oct-2020
 
 
 
@@ -31,13 +32,27 @@ Motivation
 The key motivators of this PEP are:
 
 - Encourage users to specify core metadata statically for speed,
-  ease of specification, and deterministic consumption by build
+  ease of specification, unambiguity, and deterministic consumption by
-  back-ends
+  build back-ends
 - Provide a tool-agnostic way of specifying 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
 
+To speak specifically to the motivation for static metadata, that has
+been an overall goal of the packaging ecosystem for some time. As
+such, making it easy to specify metadata statically is important. This
+also means that raising the cost of specifying data as dynamic is
+acceptable as users should skew towards wanting to provide static
+metadata.
+
+Requiring the distinction between static and dynamic metadata also
+helps with disambiguation for when metadata isn't specified. When any
+metadata *may* be dynamic, it means you never no if the absense of
+metadata is on purpose or because it is to be provided later. By
+requiring that dynamic metadata be specified, it disambiguates the
+intent when metadata goes unspecified.
+
 This PEP does **not** attempt to standardize all possible metadata
 required by a build back-end, only the metadata covered by the
 `core metadata`_ specification which are very common across projects
@@ -82,10 +97,8 @@ 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
+remove, add or change data that has been statically specified. Only
-to make data more accurate/static when possible. For example, a version
+when a field is marked as `dynamic` may a tool provide a "new" value.
-can become more specific when building a wheel (e.g. adding a local
-version), but it cannot become less specific.
 
 
 Details
@@ -216,10 +229,6 @@ error for unsupported content-types.
 
 The Python version requirements of the project.
 
-Build back-ends MAY try to backfill appropriate
-``Programming Language :: Python`` `trove classifiers`_ based on what
-the user specified for this field.
-
 ``license``
 '''''''''''
 - Format: Table
@@ -244,10 +253,7 @@ error if the metadata specifies both keys.
 A practical string value for the ``license`` key has been purposefully
 left out to allow for a future PEP to specify support for SPDX_
 expressions (the same logic applies to any sort of "type" field
-specifying what license the ``file`` or ``text`` represents). If such
+specifying what license the ``file`` or ``text`` represents).
-support comes to fruition and a tool can unambiguously identify the
-license specified, then the tool MAY fill in the appropriate trove
-classifiers.
 
 ``authors``/``maintainers``
 '''''''''''''''''''''''''''
@@ -286,7 +292,7 @@ Using the data to fill in `core metadata`_ is as follows:
 3. If both ``email`` and ``name`` are provided, the value goes in
    ``Author-email``/``Maintainer-email`` as appropriate, with the
    format ``{name} <{email}>``.
-
+4. Multiple values should be separated by commas.
 
 ``keywords``
 ''''''''''''
@@ -320,9 +326,6 @@ The keywords for the project.
 
 `Trove classifiers`_ which apply to the project.
 
-Build back-ends MAY automatically fill in extra trove classifiers
-if the back-end can deduce the classifiers from the provided metadata.
-
 ``urls``
 ''''''''
 - Format: Table, with keys and values of strings
@@ -641,13 +644,6 @@ other ecosystems without using terminology that is necessarily foreign to new
 programmers. It also prevents potential confusion with ``requires`` in the
 ``[build-system]`` table as specified in :pep:`518`.
 
-Support ``Maintainers``/``Maintainers-email``
----------------------------------------------
-When discussing how to support ``Authors``/``Authors-email``, the question was
-brought up as to how exactly authors differed from maintainers. As this was
-never clearly defined and no one could come up with a good definition, the
-decision was made to drop the concept of maintainers.
-
 Drop ``maintainers`` to unify with ``authors``
 ----------------------------------------------
 As the difference between ``Authors`` and ``Maintainers`` fields in
@@ -701,6 +697,18 @@ though, the idea of updating ``pyproject.toml`` was not generally
 liked, and so the idea was rejected in favour of separately pursuing
 standardizing metadata in sdists.
 
+Allow tools to add/extend data
+------------------------------
+In an earlier version of this PEP, tools were allowed to extend data
+for fields. For instance, build back-ends could take the version
+number and add a local version for when they built the wheel. Tools
+could also add more trove classifiers for things like the license or
+supported Python versions.
+
+In the end, though, it was thought better to start out stricter and
+contemplate loosening how static the data could be considered based
+on real-world usage.
+
 
 Open Issues
 ===========