<div dir="ltr"><div><div><div><div>the PyPA site has a PEP reference that includes details on implementation: <br><br> <a href="https://www.pypa.io/en/latest/peps">https://www.pypa.io/en/latest/peps</a><br></div><div><br></div>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.<br><br>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.<br><br></div>For example, the PUG references PEP440 in a few places.<br><br></div>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.<br><br></div>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.<br><div><div><div><div><div><div><br></div></div></div></div></div></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Apr 19, 2015 at 1:21 AM, holger krekel <span dir="ltr"><<a href="mailto:holger@merlinux.eu" target="_blank">holger@merlinux.eu</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
I'd appreciate a "current packaging specs" site which ideally also states<br>
how pypa tools support it, since which version.<br>
<br>
holger<br>
<div class="HOEnZb"><div class="h5"><br>
On Fri, Apr 17, 2015 at 16:18 -0400, Nick Coghlan wrote:<br>
> Daniel's started work on a new revision of the wheel specification,<br>
> and it's crystallised a concern for me that's been building for a<br>
> while: the Python Enhancement Proposal process is fundamentally a<br>
> *change management* process and fundamentally ill-suited to acting as<br>
> a *hosting service* for the resulting reference documentation.<br>
><br>
> This is why we're seeing awkward splits like the one I have in PEP<br>
> 440, where the specification itself is up top, with the rationale for<br>
> changes below, and the large amounts of supporting material in PEP<br>
> 426, where the specification is mixed in with a lot of background and<br>
> rationale that isn't relevant if you just want the technical details<br>
> of the latest version of the format.<br>
><br>
> It also creates a problem where links to PEP based reference documents<br>
> are fundamentally unstable - when we define a new version of the wheel<br>
> format in a new PEP then folks are going to have to follow the daisy<br>
> chain from PEP 427 through to the new PEP, rather than having a stable<br>
> link that automatically presents the latest version of the format,<br>
> perhaps with archived copies of the old version readily available.<br>
><br>
> I think I see a way to resolve this, and I believe it should be fairly<br>
> straightforward: we could create a "specifications" section on<br>
> <a href="http://packaging.python.org" target="_blank">packaging.python.org</a>, and as we next revise them, we start migrating<br>
> the specs themselves out of the PEP system and into<br>
> <a href="http://packaging.python.org" target="_blank">packaging.python.org</a>. This would be akin to the change in the Python<br>
> 3.3, where the specification of the way the import system worked<br>
> finally moved from PEP 302 into the language reference.<br>
><br>
> Under that model, the wheel 2.0 would be specifically focused on<br>
> describing and justifying the *changes* between 1.0 and 2.0, but the<br>
> final spec itself would be a standalone document living on<br>
> <a href="http://packaging.python.org" target="_blank">packaging.python.org</a>, and prominently linked to from both PEP 427<br>
> (which it would Supersede) and from the new PEP.<br>
><br>
> This approach also gives a much nicer model for fixing typos in the<br>
> specifications - those would just be ordinary GitHub PR's on the<br>
> <a href="http://packaging.python.org" target="_blank">packaging.python.org</a> repo, rather than needing to update the PEPs<br>
> repo.<br>
><br>
> Thoughts?<br>
><br>
> Regards,<br>
> Nick.<br>
><br>
> --<br>
> Nick Coghlan | <a href="mailto:ncoghlan@gmail.com">ncoghlan@gmail.com</a> | Brisbane, Australia<br>
> _______________________________________________<br>
> Distutils-SIG maillist - <a href="mailto:Distutils-SIG@python.org">Distutils-SIG@python.org</a><br>
> <a href="https://mail.python.org/mailman/listinfo/distutils-sig" target="_blank">https://mail.python.org/mailman/listinfo/distutils-sig</a><br>
><br>
<br>
</div></div><span class="HOEnZb"><font color="#888888">--<br>
about me: <a href="http://holgerkrekel.net/about-me/" target="_blank">http://holgerkrekel.net/about-me/</a><br>
contracting: <a href="http://merlinux.eu" target="_blank">http://merlinux.eu</a><br>
</font></span><div class="HOEnZb"><div class="h5">_______________________________________________<br>
Distutils-SIG maillist - <a href="mailto:Distutils-SIG@python.org">Distutils-SIG@python.org</a><br>
<a href="https://mail.python.org/mailman/listinfo/distutils-sig" target="_blank">https://mail.python.org/mailman/listinfo/distutils-sig</a><br>
</div></div></blockquote></div><br></div>