PEP 808: how to teach update

peps/pep-0808.rst

@@ -17,9 +17,9 @@ Abstract
 ========
 
 This PEP relaxes the constraint on dynamic metadata listed in the ``[project]``
-section in ``pyproject.toml`` to allow the static portion of mixed metadata to
-be defined in the normal location if the field is a table or array by having
-the dynamic fields extend the static ones.
+section in ``pyproject.toml`` to allow a static portion of mixed metadata to be
+defined in the normal location if the field is a table or array by having the
+dynamic fields extend the static ones.
 
 This allows users to opt into allowing a backend to extend metadata while still
 keeping the static portions of the metadata defined in the standard location in
@@ -317,19 +317,26 @@ a static component to existing dynamic metadata support.
 How to Teach This
 =================
 
+If you currently have dynamic metadata, but some list or table entries are
+known statically, you can now make that explicit by adding them to the
+corresponding static entry in the project table, while keeping the entry in the
+``project.dynamic`` list to allow the dynamic portion to be added by your build
+backend.
+
 The current guides that state metadata must not be listed in both ``[project]``
-and ``project.dynamic`` can be updated to say that some fields can be extended
-by ``project.dynamic``. Since dynamic metadata is already an advanced concept,
-this will likely not affect most existing tutorial material aimed at
-introductory packaging.
+and ``project.dynamic`` can be updated to say that lists and tables marked with
+``project.dynamic`` can still have static entries. Since dynamic metadata is
+already an advanced concept, this will likely not affect most existing tutorial
+material aimed at introductory packaging.
 
 The ``pyproject.toml`` `specification <pyprojectspec>`__ will be updated to
 include the behavior of fields when specified and also listed in the dynamic
 field.
 
-It should also be noted that specifying something in dynamic will require any
-tool that requires the full metadata to invoke the backend even if it is
-partially statically specified, so it should not be used unless necessary.
+It should also be noted that specifying something in ``dynamic`` will require
+any tool that requires the full metadata to invoke the backend even if it is
+partially statically specified, so it should not be used unless necessary, just
+like any other dynamic metadata.
 
 
 Rejected Ideas