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

[Marcus Smith]

the PyPA site has a PEP reference that includes details on implementation:

    https://www.pypa.io/en/latest/peps

I don't think we need another reference in the Packaging User Guide
(PUG).   We could mention that the PyPA one exists in the PUG.

As for user-facing PEP docs, I think the docs for PUG/pip/setuptools/wheel
etc.. should handle that inline, and act as the layer that references (if
need be) the correct PEP that applies to the feature being described.

For example, the PUG references PEP440 in a few places.

Ideally, it should be a requirement to update the docs for the major
projects (and the PUG) *before* releasing a PEP-implementations into those
projects.

For example, a round of docs PRs prior to the release of PEP440 into pug &
pip  could have likely prevented the confusion over the meaning  of ">"
that unfortunately had to be sorted out after the release.


On Sun, Apr 19, 2015 at 1:21 AM, holger krekel <holger at merlinux.eu> wrote:

>
> I'd appreciate a "current packaging specs" site which ideally also states
> how pypa tools support it, since which version.
>
> holger
>
> On Fri, Apr 17, 2015 at 16:18 -0400, Nick Coghlan 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?
> >
> > Regards,
> > Nick.
> >
> > --
> > Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
> > _______________________________________________
> > Distutils-SIG maillist  -  Distutils-SIG at python.org
> > https://mail.python.org/mailman/listinfo/distutils-sig
> >
>
> --
> about me:    http://holgerkrekel.net/about-me/
> contracting: http://merlinux.eu
> _______________________________________________
> Distutils-SIG maillist  -  Distutils-SIG at python.org
> https://mail.python.org/mailman/listinfo/distutils-sig
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20150419/0eed31ae/attachment.html>