[Distutils] Idea: move accepted interoperability specifications to packaging.python.org

[Donald Stufft]

> On Apr 17, 2015, at 4:18 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> 
> Daniel's started work on a new revision of the wheel specification,
> and it's crystallised a concern for me that's been building for a
> while: the Python Enhancement Proposal process is fundamentally a
> *change management* process and fundamentally ill-suited to acting as
> a *hosting service* for the resulting reference documentation.
> 
> This is why we're seeing awkward splits like the one I have in PEP
> 440, where the specification itself is up top, with the rationale for
> changes below, and the large amounts of supporting material in PEP
> 426, where the specification is mixed in with a lot of background and
> rationale that isn't relevant if you just want the technical details
> of the latest version of the format.
> 
> It also creates a problem where links to PEP based reference documents
> are fundamentally unstable - when we define a new version of the wheel
> format in a new PEP then folks are going to have to follow the daisy
> chain from PEP 427 through to the new PEP, rather than having a stable
> link that automatically presents the latest version of the format,
> perhaps with archived copies of the old version readily available.
> 
> I think I see a way to resolve this, and I believe it should be fairly
> straightforward: we could create a "specifications" section on
> packaging.python.org, and as we next revise them, we start migrating
> the specs themselves out of the PEP system and into
> packaging.python.org. This would be akin to the change in the Python
> 3.3, where the specification of the way the import system worked
> finally moved from PEP 302 into the language reference.
> 
> Under that model, the wheel 2.0 would be specifically focused on
> describing and justifying the *changes* between 1.0 and 2.0, but the
> final spec itself would be a standalone document living on
> packaging.python.org, and prominently linked to from both PEP 427
> (which it would Supersede) and from the new PEP.
> 
> This approach also gives a much nicer model for fixing typos in the
> specifications - those would just be ordinary GitHub PR's on the
> packaging.python.org repo, rather than needing to update the PEPs
> repo.
> 
> Thoughts?

Would Daniel’s change still require a PEP to make it or would it just
require a PR? If we’re going to make a GitHub repository the source
of truth for specs would it make sense to just ditch PEPs all together
and use Pull Requests to handle things? They can have discussion and
comments and stuff baked into them which could function to capture the
“Why”.

I’m not sure it’s super useful in general, I don’t see much difference
between the way we’re using PEPs and the way RFCs are written. They
often have some light rationalization inside of the meat of the RFC and
then in the Appendix they have more in depth rationalization.

A bigger problem I have so far is that we don’t really have any user
facing documentation. For some things that’s fine (you don’t need a user
facing documentation for Wheels, because users shouldn’t generally be
manually constructing them), but things like PEP 440, or parts of PEP 426
we don’t have any real information to point users at to tell them what
they can and can’t do that isn’t essentially a spec to implement it.


---
Donald Stufft
PGP: 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 801 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20150417/e00fdede/attachment.sig>