On 5 September 2015 at 14:24, Marcus Smith <qwc...@gmail.com> wrote: >> 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.
Right, having more user friendly introductions on packaging.python.org is a good idea, but it's a separate question. To address that specific problem, we can paraphrase the semantic versioning compatibility section from PEP 440: https://www.python.org/dev/peps/pep-0440/#semantic-versioning I filed a PR along those lines, inserting it as a new subsection under "Configuring your project" > 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) Right. Another potential benefit of this approach is that it means we can more easily cross-link from the implementor facing specifications to end user facing parts of the user guide - at the moment, there's no standard discoverability path from PEPs like PEP 440 to packaging.python.org at all. Cheers, Nick. -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig