Packaging PEPs: Update headers & link canonical PyPA specs

[CAM-Gerlach]

While the specifications defined or modified in a number of packaging PEPs have been migrated to the PyPA specifications page on packaging.python.org, many/most such PEPs are missing a clear indication of this identifying and linking to the canonical spec and mentioning the process for changing them (and the ones that do are highly inconsistent in placement, wording and format).

As such, it is not clear to many users that the PEPs are no longer the canonical, up to date specification, leading to them using and referring to outdated information, which will only get worse over time as further updates are made. Furthermore, this causes a steady stream of users come here with issues/PRs related to these specs that should rather be following the PyPA specification update process and directed to the packaging.python.org GitHub, the Packaging Discourse and/or a new PEP instead.

Therefore, I've updated all the relevant PEPs with a standard "Important"-level admonition (which can be easily be dropped in to future such PEPs, aside from a change in the link; we could probably define a directive for this, but that's likely overkill and limits flexibility if/when we need it) that states this and links to the canonical spec and the PyPA update process.

EDIT: I've rebased this PEP to use the canonical-pypa-spec directive added in #2702 , so now the wording is standardized between PEPs and can be easily changed in one go (and we could also easily create custom subclasses if needed).

Additionally, I noticed some older PEPs didn't have the appropriate replaces, superceded by, etc. header fields, and/or were not marked as superseded, which I updated. Also, I elided a section on provisional acceptance on a PEP that is now Final, fixed a couple other PEP links, and updated/filled out a couple other missing headers, mostly related to Post-History and Resolution, that I came across in the process.

Required PR #2691 for the admonitions to display as intended.

[CAM-Gerlach]

To note, I'll fix the admonition styles in a separate PR that should precede this one.

Edit: Opened as #2691

[CAM-Gerlach]

FYI, updated the PEP after I merged #2691 so now the admonitions display as intended.

[CAM-Gerlach]

I've marked this as draft, since instead of copy/pasting the admonition to every relevant file, making it a chore to add and update, I've instead added, in #2702 , a new subclass of the admonition introduced there specifically for PyPA specs. Once that gets merged, I'll rebase this PR to use it instead. Please let me know what you think of the text over there, thanks!

[CAM-Gerlach]

Oops, sorry—didn't mean to re-request review until I had incorporated the revised banner from #2702 (but I welcome any feedback on the proposed text over there).

[CAM-Gerlach]

@pradyunsg @pfmoore I've rebased this PEP to use the revised, standardized admonition wording added in #2702 , which incorporated your feedback from over here. If we need to tweak it further, add custom text or even a subclass, its easy to do so—just let me know. Otherwise, this should be ready to go. Thanks!

[JelleZijlstra]

Looks good from my perspective but I'd like to see an approval from one of the packaging folks too.

[CAM-Gerlach]

Hey @pradyunsg @pfmoore any further feedback here?

[pfmoore]

Given that the change still states that the documents are "historical", a wording that I objected to above, no I really don't have anything to add. My feelings remain the same, I don't think calling the documents "historical" is helpful (no matter how much we debate nuances here, where the reader will never see it...)

[CAM-Gerlach]

(Also pinging @brettcannon , since he's both a PEP editor and involved in the packaging community)

I previously responded to those concerns in some detail above. It is, and AFAIK always has been generally the case that PEPs, at least once marked Final, are considered historical documents rather than living specifications or up-to-date documentation. Per PEP 1:

Once resolution is reached, a PEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the Language Reference for core features, the Library Reference for standard library modules or the PyPA Specifications for packaging.

In particular, these PEPs all are marked Final and have their canonical specification migrated to the PyPA specs site, most if not all of which have since been updated by other PEPs (e.g. PEP 685) as well as smaller changes, and they are no longer kept up to date here—a policy which I had thought you were fully supportive of, no?

Furthermore, practically speaking, we get a stream of users opening issues/PRs about PEPs, including packaging ones, not reading carefully and thinking otherwise, and many users (even experienced community members) looking to the PEPs rather than the specs, docs, etc. as current documentation rather than rather than the historical change proposals that they generally are.

Therefore, I'm not sure I understand the harm in letting users know this, and guiding them toward the canonical spec instead, unless they actually are looking to read the historical change proposal or historical versions of the spec, in which they do care about that nuance and the "historical" wording describes what they are looking for.

[pfmoore]

🤷 I know you've responded, and I simply disagree with you. It's not that big a deal, we'll just have to agree to differ on this - I don't think I have any sort of absolute veto here. However, I don't know how differences of opinion like this do get resolved, so I can't suggest what the next step is here, sorry.

[CAM-Gerlach]

A difference of personal opinions is all well and good, which could be resolved by soliciting additional opinions on the matter, as we have. However, I feel (which I suppose is itself an opinion, heh) I've laid out a detailed and specific rationale for PEPs being historical documents, directly supported by PEP 1, SC and repo policy, and why it is a net benefit to be clear to users about such, supported by both overall principles and practical experience. If there are flaws in that reasoning, as well there might be, I would of course welcome others pointing those out, which would be the fastest way to move this forward. Or, I'd welcome the opportunity to more fully understand your own thinking, in light of the points and questions I raised.

Otherwise, if there is agreement among the packaging community members as to a different proposed wording for the banner (especially for anything past the first line that applies to PEPs in general rather than being PyPA-specific), then I of course will implement whatever people agree on so as to move this PR forward.

[pradyunsg]

I don't have any opinions on the changes to the headers or the "historical" discussion -- the links look correct and useful. :)

LGTM.

[pfmoore]

Or, I'd welcome the opportunity to more fully understand your own thinking, in light of the points and questions I raised.

To be clear, you requested my review here. If you hadn't, I probably wouldn't have noticed this or made any comment. So please don't assume I'm in any way trying to block this change, or that it matters a huge amount to me. But having been asked my opinion, I gave it - I don't think that using the term "historical" gives the right impression. For example, there's nothing "historical" about the Metadata 2.1 spec - it's still the official, formal definition of the rules which a project that publishes metadata with the version 2.1 should follow. Sure, we now say that projects should use metadata 2.2, but that doesn't stop projects using 2.1. And right now, nothing uses 2.2 because PyPI doesn't accept it. So that means the Metadata 2.1 spec is still the correct specification for tools that want to publish metadata that is of practical use. Someone coming to that PEP, finding it marked as "historical" and being directed to packaging.python.org, where the only spec is for 2.2, will quite rightly be confused. The same applies to all older metadata versions such as 1.2. They may no longer be current, but you'll still encounter them, and where's the non-"historical" description of the rules that apply?

I don't have an alternative suggestion, other than "leave things alone". The current situation isn't perfect, but I don't consider the proposed change any better. And frankly, I think we've spent far longer debating nuances here than the situation warrants. There are much more pressing tasks that we all could be doing.

So do what you think is best. I won't be approving this change, but I also won't care a huge amount if you disagree with (or simply ignore) my reservations. I'm just going to drop out of the discussion at this point.

[brettcannon]

I say let's try keeping the "historical document" in and merge this PR. If it causes confusion we can take it out with a single commit.

[CAM-Gerlach]

Hey, sorry for not responding a while ago when I intended. I wanted to make sure I had enough time to fully consider @pfmoore 's detailed and thoughtful response (which I really appreciate), and try to soften my at times overly-opinionated and argumentative tendencies (that can often cause unnecessary friction for others and consuming my and others' precious time and energy debating relatively minor points, which I apologize for, and will try to continue to work on in the future). I just lost track of it amidst the Artemis 1 launch right around the same time.

In any case, I'm happy to do whatever others think is best, whether that's keep the sentence, remove it or replace it with something else, to keep this moving along.