pypa
Migrating interoperability specifications to PyPUG
I have some time at the moment to work on upstream process improvement, and one of the things I'd like to tidy up is the change management process for interoperability specifications. Some relevant previous discussions:
- PyPA, PEPs & BDFL-Delegates: https://mail.python.org/pipermail/distutils-sig/2015-September/026810.html
- Potentially moving away from PEPs as the primary spec reference URLs: https://mail.python.org/pipermail/distutils-sig/2015-April/026206.html
- Including more user centric summaries of the specifications in the packaging user guide: https://github.com/pypa/python-packaging-user-guide/issues/151
Since that last discussion, @dstufft, @nlhkabu and @ddbeck have done a lot more design work on Warehouse and the user guide, so I've now come around to the view that the PyPA internal docs are likely to be a better home.
Rather than using PEP 440 or PEP 508 as guinea pigs, I'm thinking a better starting point might be PEP 376 (the database of installed Python distributions), since we can tweak the description on pypa.io to specifically cover the interoperability spec parts that pip implements, and omit the standard library API parts.
I'll put together a pull request along those lines, adding a new "PyPA Specifications" section, with process details (based on the first email linked above), and a section on the RECORD file and the directory naming scheme.
(I don't currently have access to assign this to myself, so if I could be added, that would be great)
Just to be clear, you want to move the PEPs out of the PEP repository and into uh, this one I guess? Or what specifically is the plan?
Not quite. What I'd like to do is shift to a model closer to the way CPython uses the PEP process:
- the interoperability specifications that people actually use to write software live in this repo (and are referenced by stable URLs)
- the PEP process is used to manage changes to the specifications, but the spec updates themselves would be implemented as PRs against this repo.
That way, if you just want the current spec, that's always readily available, and you only need to look at the PEPs to understand why the spec is the way it is.
Initial PR: https://github.com/pypa/pypa.io/pull/12
(I'm also working on an update to the roadmap to point to this issue from the relevant sections)
distutils-sig thread: https://mail.python.org/pipermail/distutils-sig/2016-January/028060.html
After reflecting on the PR and likely future workflows, I've switched to favouring a split approach where we put the process definition here (since it's really only relevant to PyPA & distutils-sig members), but have the specifications themselves on packaging.python.org.
The main purposes of that is to keep the packaging specifications on the same standing as the Language Reference and Library Reference in terms of "brand recognition" for their top level domain.
I implemented the split where the process guide is here, but the specifications themselves stay on *.python.org:
Process PR: https://github.com/pypa/pypa.io/pull/14 Specifications PR: https://github.com/pypa/python-packaging-user-guide/pull/213
Next steps:
- [x] update for the migration of the main PEPs repo to GitHub
- [x] update the process description to allow errata & minor amendments to be handled as PyPUG issues and pull requests, rather than full PEPs
- [ ] update the PEPs themselves with links pointing to the appropriate section in https://packaging.python.org/en/latest/specifications/ for errata & amendments
Added an extra task bullet to account for the migration of https://github.com/python/peps to GitHub
https://github.com/pypa/pypa.io/issues/19 implements the first 2 bullet points in the task list
@di split the specifications page up into multiple pages, and migrated the full core metadata description over to packaging.python.org in https://github.com/pypa/python-packaging-user-guide/pull/386