> 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
If I may, I don't think that really captures Nick's idea. I think it's about clearly distinguishing the following: 1) Current Specs (for metadata, versioning, pypi etc..) 2) Proposals to adjust or add to the Current Specs 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... - So, for #1, maintain documents in PyPUG - For #2, keep using PEPs - As PEPs are accepted, update the Spec docs (the version history can mention what PEP drove the change) 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. Marcus On Fri, Sep 4, 2015 at 8:06 PM, Donald Stufft <don...@stufft.io> wrote: > On September 4, 2015 at 10:56:38 PM, Nick Coghlan (ncogh...@gmail.com) > wrote: > > On 5 September 2015 at 12:14, Donald Stufft wrote: > > > On September 4, 2015 at 10:12:08 PM, Nick Coghlan (ncogh...@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 > > > _______________________________________________ > Distutils-SIG maillist - Distutils-SIG@python.org > https://mail.python.org/mailman/listinfo/distutils-sig >
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
