On September 4, 2015 at 10:56:38 PM, Nick Coghlan (ncoghlan@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@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