On 8 September 2015 at 04:13, Marcus Smith
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@gmail.com | Brisbane, Australia