[Distutils] "Specs" vs "Proposals"

Nick Coghlan ncoghlan at gmail.com
Tue Sep 8 03:52:39 CEST 2015

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


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

More information about the Distutils-SIG mailing list