On 8 September 2015 at 04:13, Marcus Smith 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


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.


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

Search Discussions

Discussion Posts


Related Discussions

Discussion Navigation
viewthread | post
posts ‹ prev | 4 of 4 | next ›
Discussion Overview
groupdistutils-sig @
postedSep 7, '15 at 6:13p
activeSep 8, '15 at 1:52a



site design / logo © 2018 Grokbase