<div dir="ltr"><div>> I don't have a specific problem with the specs living somewhere else </div><div>> as well, I just don't think moving a lengthy document full of edge cases </div><div>> from one location to another is going to make things better</div><div><br></div><div>If I may, I don't think that really captures Nick's idea.  </div><div><br></div><div>I think it's about clearly distinguishing the following:</div><div><br></div><div>1) Current Specs (for metadata, versioning, pypi etc..)</div><div>2) Proposals to adjust or add to the Current Specs</div><div><br></div><div>We don't have a clear distinction right now.  We just have a series of PEPs, and it's work to figure out where the actual current spec is at, in the noise of rationales and transition plans etc...</div><div><br></div><div>- So, for #1, maintain documents in PyPUG</div><div>- For #2, keep using PEPs</div><div>- As PEPs are accepted, update the Spec docs (the version history can mention what PEP drove the change)</div><div><br></div><div>And separate from all of this I think is your idea that regular Usage docs should be modified as well, as PEPs are accepted, which I think is great.</div><div><br></div><div>Marcus</div><div><br></div><div><br></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Sep 4, 2015 at 8:06 PM, Donald Stufft <span dir="ltr"><<a href="mailto:donald@stufft.io" target="_blank">donald@stufft.io</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On September 4, 2015 at 10:56:38 PM, Nick Coghlan (<a href="mailto:ncoghlan@gmail.com">ncoghlan@gmail.com</a>) wrote:<br>
<span class="">> On 5 September 2015 at 12:14, Donald Stufft wrote:<br>
> > On September 4, 2015 at 10:12:08 PM, Nick Coghlan (<a href="mailto:ncoghlan@gmail.com">ncoghlan@gmail.com</a>) wrote:<br>
> >> It's only the interoperability specs where we currently follow the RFC<br>
> >> model of having the same document describe both the end result *and*<br>
> >> the rationale for changes from the previous version, and I mostly find<br>
> >> it to be a pain.<br>
> >><br>
> ><br>
> > I'm not sure that I follow what you’re saying here, can you describe what your<br>
> > ideal situation would look like?<br>
><br>
> 1. We add a new section to <a href="http://packaging.python.org" rel="noreferrer" target="_blank">packaging.python.org</a> for "Specifications".<br>
> The specification sections of approved PEPs (compatibility tags, wheel<br>
> format, version specifiers, dist-info directories) get added there.<br>
> API specifications for index servers may also be added there.<br>
><br>
> 2. Interoperability PEPs become proposals for new <a href="http://packaging.python.org" rel="noreferrer" target="_blank">packaging.python.org</a><br>
> specifications or changes to existing specifications, rather than<br>
> specifications in their own right.<br>
><br>
> 3. Each specification has a "version history" section at the bottom,<br>
> which links to the PEPs that drove each update.<br>
><br>
> This way, the PEPs can focus on transition plans, backwards<br>
> compatibility constraints, and the rationale for particular changes,<br>
> etc, but folks wanting "just the current spec, thanks" can look at the<br>
> latest version on <a href="http://packaging.python.org" rel="noreferrer" target="_blank">packaging.python.org</a> without worrying about the<br>
> history.<br>
><br>
> It also means that the specs themselves (whether additions or updates)<br>
> can be prepared as <a href="http://packaging.python.org" rel="noreferrer" target="_blank">packaging.python.org</a> PRs.<br>
><br>
<br>
</span>Personally I don't have much of a problem with the specs living as PEPs, I<br>
think a bigger problem is that we're producing specs that have end user impact<br>
without anything designed for end users to go along with them. PEP 440 is a<br>
wonderful example of this, the spec of PEP 440 goes into lots of edge cases and<br>
describes the reasons why particular decisions were made and all of that jazz.<br>
I think all of that data is useful when you're implementing PEP 440 because it<br>
helps inform how someone interprets the spec in situations where it may be<br>
ambiguous.<br>
<br>
What I don't think is useful is having no answer to someone who asks "What's<br>
a valid version for a Python package" except "here go read this massive<br>
document which covers tons of edge cases which you don't really need to care<br>
about unless you're pip/PyPI/setuptools etc".<br>
<br>
I guess for me then, the ideal situation would be to keep using PEPs for the<br>
actual specification/RFC like documentation, but when that has end user impact<br>
then a requirement is that it comes with a PR to <a href="http://packaging.python.org" rel="noreferrer" target="_blank">packaging.python.org</a> that<br>
gives us end user documentation for the spec, before the spec can be accepted<br>
(or finalized or whatever the right terminology is). I mean, I don't have a<br>
specific problem with the specs living somewhere else as well, I just don't<br>
think moving a lengthy document full of edge cases from one location to another<br>
is going to make things better unless we start producing end user focused<br>
documentation, and in many cases it may make it worse since understanding a<br>
spec fully often requires understanding why certain decisions were made.<br>
<span class="im HOEnZb"><br>
-----------------<br>
Donald Stufft<br>
PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA<br>
<br>
<br>
</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" rel="noreferrer" target="_blank">https://mail.python.org/mailman/listinfo/distutils-sig</a><br>
</div></div></blockquote></div><br></div>