From 2749addb7695b121775468eff8974da0df510bc9 Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Tue, 6 Jun 2023 22:22:48 -0500 Subject: [PATCH] Temp commit of further glossarization changes --- peps/pep-0639.rst | 70 +++++++++++++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 29 deletions(-) diff --git a/peps/pep-0639.rst b/peps/pep-0639.rst index 7c03c0482c1..cb7acb8eb49 100644 --- a/peps/pep-0639.rst +++ b/peps/pep-0639.rst @@ -486,8 +486,9 @@ As it adds new fields, this PEP updates the Core Metadata version to 2.4. Add ``License-Expression`` field '''''''''''''''''''''''''''''''' -The ``License-Expression`` optional field is specified to contain a text string -that is a valid SPDX license expression, as defined herein. +The ``License-Expression`` optional :term:`Core Metadata field>` +is specified to contain a text string +that is a valid SPDX :term:`license expression`, as defined herein. Publishing tools SHOULD issue an informational warning if this field is missing, and MAY raise an error. Build tools MAY issue a similar warning, @@ -501,7 +502,7 @@ Version 2.2 or a later compatible version. When used in the ``License-Expression`` field and as a specialization of the SPDX license expression definition, a license expression can use the -following license identifiers: +following :term:`license identifier`\s: - Any SPDX-listed license short-form identifiers that are published in the `SPDX License List `__, version 3.17 or any later compatible @@ -533,10 +534,12 @@ a valid license expression, build and publishing tools: the normalization process results in changes to the ``License-Expression`` field contents. -For all newly-upload distributions that include a -``License-Expression`` field, the `Python Package Index (PyPI) `__ MUST +For all newly-upload :term:`distribution archive`\s +that include a ``License-Expression`` field, +the `Python Package Index (PyPI) `__ MUST validate that it contains a valid, case-normalized license expression with -valid identifiers (as defined here) and MUST reject uploads that do not. +valid identifiers (as :ref:`defined here <639-license-expression-definition>`) +and MUST reject uploads that do not. PyPI MAY reject an upload for using a deprecated license identifier, so long as it was deprecated as of the above-mentioned SPDX License List version. @@ -547,34 +550,38 @@ version. Add ``License-File`` field '''''''''''''''''''''''''' -Each instance of the ``License-File`` optional field is specified to contain -the string representation of the path in the project source tree, relative to -the project root directory, of a license-related file. +Each instance of the ``License-File`` optional :term:`Core Metadata field>` +is specified to contain +the string representation of the path in the :term:`project source tree`, +relative to the :term:`project root directory`, of a license-related file. It is a multi-use field that may appear zero or more times, each instance listing the path to one such file. Files specified -under this field could include license text, author/attribution information, +by this field could include license text, author/attribution information, or other legal notices that need to be distributed with the package. As :ref:`specified by this PEP <639-spec-project-formats>`, its value -is also that file's path relative to the root license directory in both -installed projects and the standardized distribution package types. +is also that file's path relative to the :term:`root license directory` +in both :term:`installed project`\s +and the standardized :term:`Distribution Package` types. In other legacy, non-standard or new distribution package formats and -mechanisms of accessing and storing Core Metadata, the value MAY correspond -to the license file path relative to a format-defined root license directory. +mechanisms of accessing and storing :term:`Core Metadata`, +the value MAY correspond to the license file path +relative to a format-defined root license directory. Alternatively, it MAY be treated as a unique abstract key to access the license file contents by another means, as specified by the format. -If a ``License-File`` is listed in a source or built distribution's core -metadata, that file MUST be included in the distribution at the specified path -relative to the root license directory, and MUST be installed with the -distribution at that same relative path. +If a ``License-File`` is listed in a :term:`source distribution` +or :term:`Built Distribution`'s Core Metadata, +that file MUST be included in the :term:`distribution archive` +at the specified path relative to the root license directory, +and MUST be installed with the :term:`project` at that same relative path. The specified relative path MUST be consistent between project source trees, source distributions (sdists), built distributions (:term:`Wheel`\s) and installed projects. Therefore, inside the root license directory, packaging tools MUST reproduce the directory structure under which the -source license files are located relative to the project root. +source license files are located relative to the project root directory. Path delimiters MUST be the forward slash character (``/``), and parent directory indicators (``..``) MUST NOT be used. @@ -584,10 +591,12 @@ Build tools MAY and publishing tools SHOULD produce an informative warning if a built distribution's metadata contains no ``License-File`` entries, and publishing tools MAY but build tools MUST NOT raise an error. -For all newly-uploaded distribution packages that include one or more -``License-File`` fields and declare a ``Metadata-Version`` of ``2.4`` or -higher, PyPI SHOULD validate that the specified files are present in all -uploaded distributions, and MUST reject uploads that do not validate. +For all newly-uploaded :term:`distribution archive`\s that include one or more +``License-File`` fields in their Core Metadata +and declare a ``Metadata-Version`` of ``2.4`` or higher, +PyPI SHOULD validate that all specified files are present in that +:term:`distribution archive`\s, +and MUST reject uploads that do not validate. .. _639-spec-field-license: @@ -595,19 +604,21 @@ uploaded distributions, and MUST reject uploads that do not validate. Deprecate ``License`` field ''''''''''''''''''''''''''' -The legacy unstructured-text ``License`` field is deprecated and replaced by -the new ``License-Expression`` field. Build and publishing tools MUST raise -an error if both these fields are present and their values are not identical, +The legacy unstructured-text ``License`` :term:`Core Metadata field>` +is deprecated and replaced by the new ``License-Expression`` field. +Build and publishing tools MUST raise an error +if both these fields are present and their values are not identical, including capitalization and excluding leading and trailing whitespace. If only the ``License`` field is present, such tools SHOULD issue a warning informing users it is deprecated and recommending ``License-Expression`` instead. -For all newly-uploaded distributions that include a +For all newly-uploaded :term:`distribution archive`\s that include a ``License-Expression`` field, the `Python Package Index (PyPI) `__ MUST reject any that specify a ``License`` field and the text of which is not -identical to that of ``License-Expression``, as defined in this section. +identical to that of ``License-Expression``, +as :ref:`defined here <639-license-expression-definition>`. Along with license classifiers, the ``License`` field may be removed from a new version of the specification in a future PEP. @@ -618,7 +629,8 @@ new version of the specification in a future PEP. Deprecate license classifiers ''''''''''''''''''''''''''''' -Using license `classifiers `__ in the ``Classifier`` field +Using :term:`license classifier`\s +in the ``Classifier`` :term:`Core Metadata field>` (`described in the Core Metadata specification `__) is deprecated and replaced by the more precise ``License-Expression`` field.