How to propose new specs

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.

1 Like

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…)

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

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.

1 Like

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!

No, the PR covers everything I had in mind.

1 Like

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. :slight_smile:

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.