Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PEP 639: Further update per discussion, w/flat license key, etc. #2705

Merged
merged 11 commits into from
Aug 3, 2022

Conversation

CAM-Gerlach
Copy link
Member

@CAM-Gerlach CAM-Gerlach commented Jul 10, 2022

At long last, the next (and hopefully final) round of substantive PEP 639 (PEP-639) updates has arrived, based on the consensus of recent (and by now, not so recent) community discussions.

See the preview here

I was initially going to make the Terminology section into a Sphinx glossary and link the terms on first and prominient uses for clarity, but to speed things up and avoid scope creep I've deferred that to an immediate followup.

In a final followup PR, I'll reduce the length of the PEP by a further ≈two thirds (on top of substantial earlier reductions and modest further trimming here) by moving all the appendices, the "Mapping License Classifiers to SPDX Identifiers" section (previously normative) and the full rejected ideas section (minus a concise summary of the most-discussed ones) to separate ancillary files linked from the appropriate places. Since I've already set the stage for that with the work in #2531, it should be a fairly straightforward and mostly mechanical change once this PR is editorially reviewed and merged.

Substantive content changes:

  • Instead of adding a new top-level license-expression key for the license expression in the [project] table of the pyproject.toml source metadata, the PEP now specifies using the top-level string value of the license key for this purpose, which PEP 621 (PEP-621) reserved it for, and updates the license-expression and license key specs, and the examples, rejected ideas and other sections accordingly.
  • Since this makes it not possible to convert a legacy license key to the new License-Expression field at build time, and that's not really advisable anyway, it drastically simplifies the normative Converting Legacy Metadata section to just a single normative statement, and updates/removes other mentions of it accordingly, and the (already rather unhelpful) example
  • Likewise, it simplifies and refines the guidance in the Mapping classifiers to SPDX identifiers section to be more general and less focused on build time, and also allows tools to ignore redundant parent classifiers (Note: This section will be moved to an external appendix in the next PR, but I didn't move it here for ease of review)
  • The license_files directory was renamed to licenses at the request of @brettcannon and to simplify things a touch
  • The specified handling of the license.file key was a bit confused by a (apparently quite common) misunderstanding about how the specified file is used (to inject its text directly under the License field in core metadata, rather than included in distribution archives or its path specified in metadata) due to it being rather underspecified in PEP 621, which this revision corrects.
  • Bump the core metadata version to reflect acceptance of PEP 685 as Metadata 2.3
  • Bump the SPDX license list version to be up to date

Significant non-normative/editorial changes:

  • Mention implementation of drafts of this PEP in Hatch and Setuptools, and also describes previous efforts in Setuptools and Wheel that this PEP builds on more clearly, as suggested on the discussion thread
  • Reference the canonical project [source] metadata PyPA spec instead of PEP 621, use clearer language surrounding that, and update a few references to other PEPs
  • Revise the Motivations and Rationale to be less duplicative/redundant, more balanced and focused more specifically on their respective areas (providing some background and describing the problem, and introducing and justifying the proposed solution, respectively)
  • Add a short blurb making explicit the use of RFC 2119 terminology (MUST, SHOULD, etc)
  • Update PEP headers
  • Various other minor revisions to correct typos and other issues, clarify and simply the text, and improve source formatting.

pep-0639.rst Outdated Show resolved Hide resolved
@CAM-Gerlach CAM-Gerlach force-pushed the pep-639-update-license-key-etc branch 2 times, most recently from 3140037 to 75d3eda Compare July 11, 2022 08:44
@CAM-Gerlach CAM-Gerlach force-pushed the pep-639-update-license-key-etc branch from 75d3eda to e59ccc9 Compare July 11, 2022 09:53
Copy link
Member

@JelleZijlstra JelleZijlstra left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Generally looks good, but a few notes on wording

pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated
Comment on lines 146 to 151
``License :: OSI Approved :: BSD License``). However, this both requires a
substantial amount of effort to duplicate the SPDX license list and keep
it in sync, and is effectively a hard break in backward compatibility,
forcing a huge proportion of package authors to immediately update to new
classifiers (in most cases, with many possible choices that require closely
examining the project's license) immediately when PyPI deprecates the old ones.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All this is one sentence. It would be more readable if split up.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done ✔️ , I made that change, caught a few other stray spaces and such and squashed it into the same commit with yours.

pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
pep-0639.rst Outdated Show resolved Hide resolved
@CAM-Gerlach
Copy link
Member Author

Going to go ahead and merge this soon unless anyone has any last feedback, and iterate further a final followup PR making the Terminology definitionlist into a glossary, linking the terms on first use in sections for clarity, adding additional ref targets, and taking advantage of the new Intersphinx support added in #2702 to link to the PyPA specs and glossary terms, making them simpler, more robust and more useful, as well as making it easier to both convert it to a PyPA spec, and review the same (avoiding some of the problems in pypa/packaging.python.org#1111).

@CAM-Gerlach
Copy link
Member Author

Merging now, I'll make any last changes (glossary, intersphinx, etc) in a followup.

@CAM-Gerlach CAM-Gerlach changed the title PEP 639: Use flat license value instead of new key for expression & other updates PEP 639: Further update per discussion, w/flat license key, etc. Aug 3, 2022
@CAM-Gerlach CAM-Gerlach merged commit d31806f into python:main Aug 3, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants