[Distutils] "Specs" vs "Proposals"

[Nick Coghlan]

On 8 September 2015 at 04:13, Marcus Smith <qwcode at gmail.com> wrote:
> and assuming that approach, I raised a few "publishing" questions:
> 1) do we publish/render all supported versions of a certain spec, or just
> the latest
> 2) if we publish them all, then how?  do we maintain separate documents for
> distinct versions? if not, how do we do it?

Ah, I missed you'd broken this out to a new thread before replying to
the old one. My concrete proposal would be to use a structure like the
following:

    https://packaging.python.org/specifications/versioning-1.x.html
    https://packaging.python.org/specifications/compatibility-tags-1.x.html
    https://packaging.python.org/specifications/wheel-format-1.x.html

The underlying principle behind that naming scheme is that I *want* to
support revising lower level specifications (like compatibility tags),
without also revising higher level specifications to refer to the new
version. If that's *not* appropriate for a particular change, then it
suggests we may actually need a major version bump in the lower level
spec (even if it can be accounted for through a backwards compatible
change in the higher level specs).

My rationale from that comes from the proposed approach to metadata
versioning in PEP 426:

===============
Automated tools consuming metadata SHOULD warn if metadata_version is
greater than the highest version they support, and MUST fail if
metadata_version has a greater major version than the highest version
they support (as described in PEP 440 , the major version is the value
before the first dot).
===============

>From a tooling perspective, this "file per major version" approach
also creates a substantially different review workflow for minor and
major revisions. For minor revisions, the review would be of a PR
against the existing specification. For major revisions, it would be a
review of a completely new file.

My rationale behind having the "1.x" in the URL rather than just "1"
is that I see it as a subtle reminder that the specs may be updated
in-place for backwards compatible changes, and that this is by design
- we're applying iterative design principles to software distribution
interoperability specifications, so this isn't a "set it and forget it
forever" kind of exercise on the part of tooling developers.

Regards,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia