How to propose new specs

[uranusjr (Tzu-ping Chung)]

@pradyunsg

Also please file a PR against packaging.python.org adding a specification for the format, and reference that in the PEP – we’d want the specification on packaging.python.org to serve as the canonical source, with the PEP justifying the creation of the specification (in other cases, it would be the changes to the specification).

I have to admit I never really understand how this process works. Should I submit a PR now, or after the PEP is accepted? What if the PEP is eventually rejected or withdrawn? I can’t find any write-up about the what to do exactly, and there doesn’t seem to be any precedents as far as I know.

[pf_moore (Paul Moore)]

https://www.pypa.io/en/latest/specifications/#proposing-new-specifications

I have to say, that documentation wasn’t familiar to me (I wasn’t even aware that https://www.pypa.io was a site with usable content!) We probably need to better publicise PyPA processes and standards…

(BTW, that document needs updating as it says that discussions should go to distutils-sig. But I can’t immediately see where to submit PRs for that content…)

[sumanah (Sumana Harihareswara)]

@pf_moore You submit changes at https://github.com/pypa/pypa.io .

[uranusjr (Tzu-ping Chung)]

According to Updating PEP 376; making RECORD optional in installed .dist-info, it seems like the PR for PyPA specification should be sent to pypa/packaging.python.org. The pypa.io page linked above should probably be updated to include this information.

I’ll try to find some time and send a PR later this week if someone doesn’t do it first.

[sumanah (Sumana Harihareswara)]

I’ve now merged @uranusjr’s https://github.com/pypa/pypa.io/pull/56 – does any work remain to resolve the question you started this thread with, Tzu-ping? Thanks!

[uranusjr (Tzu-ping Chung)]

No, the PR covers everything I had in mind.

[pradyunsg (Pradyun Gedam)]

The way that I understand the situation is:

• the PEP contains all the information like “Why did we do <thing-we-settled-on> and not <different-thing>”
• the PR to packaging.python.org adds a page that describes <thing-we-settled-on>

Whether you want to describe <thing-we-settled-on> in the PEP’s text, is the part where I’m not 100% clear so I’m gonna say it’s whatever the PEP’s authors want to do.

[pf_moore (Paul Moore)]

Agreed. I’d argue that <thing-we-settled-on> should be in the PEP, so that the discussion has a single reference. There’s obviously a risk that way that PEP and PR get out of sync, but I don’t think that’s too bad. Plus, reading the description of what’s proposed in a (properly rendered) PEP is much easier than reading the (unrendered) diff of a PR.