[Distutils] Working toward Linux wheel support

[Donald Stufft]

On September 4, 2015 at 10:56:38 PM, Nick Coghlan (ncoghlan at gmail.com) wrote:
> On 5 September 2015 at 12:14, Donald Stufft wrote:
> > On September 4, 2015 at 10:12:08 PM, Nick Coghlan (ncoghlan at gmail.com) wrote:
> >> It's only the interoperability specs where we currently follow the RFC
> >> model of having the same document describe both the end result *and*
> >> the rationale for changes from the previous version, and I mostly find
> >> it to be a pain.
> >>
> >
> > I'm not sure that I follow what you’re saying here, can you describe what your
> > ideal situation would look like?
>  
> 1. We add a new section to packaging.python.org for "Specifications".
> The specification sections of approved PEPs (compatibility tags, wheel
> format, version specifiers, dist-info directories) get added there.
> API specifications for index servers may also be added there.
>  
> 2. Interoperability PEPs become proposals for new packaging.python.org
> specifications or changes to existing specifications, rather than
> specifications in their own right.
>  
> 3. Each specification has a "version history" section at the bottom,
> which links to the PEPs that drove each update.
>  
> This way, the PEPs can focus on transition plans, backwards
> compatibility constraints, and the rationale for particular changes,
> etc, but folks wanting "just the current spec, thanks" can look at the
> latest version on packaging.python.org without worrying about the
> history.
>  
> It also means that the specs themselves (whether additions or updates)
> can be prepared as packaging.python.org PRs.
>  

Personally I don't have much of a problem with the specs living as PEPs, I
think a bigger problem is that we're producing specs that have end user impact
without anything designed for end users to go along with them. PEP 440 is a
wonderful example of this, the spec of PEP 440 goes into lots of edge cases and
describes the reasons why particular decisions were made and all of that jazz.
I think all of that data is useful when you're implementing PEP 440 because it
helps inform how someone interprets the spec in situations where it may be
ambiguous.

What I don't think is useful is having no answer to someone who asks "What's
a valid version for a Python package" except "here go read this massive
document which covers tons of edge cases which you don't really need to care
about unless you're pip/PyPI/setuptools etc".

I guess for me then, the ideal situation would be to keep using PEPs for the
actual specification/RFC like documentation, but when that has end user impact
then a requirement is that it comes with a PR to packaging.python.org that
gives us end user documentation for the spec, before the spec can be accepted
(or finalized or whatever the right terminology is). I mean, I don't have a
specific problem with the specs living somewhere else as well, I just don't
think moving a lengthy document full of edge cases from one location to another
is going to make things better unless we start producing end user focused
documentation, and in many cases it may make it worse since understanding a
spec fully often requires understanding why certain decisions were made.

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