pulling this idea out of the "Linux wheel support" thread, since it deserves it's own thread... the idea being that we should better distinguish: 1) the current packaging "Specs" (for metadata, versions, etc...) vs 2) Proposals to change them currently, we just have PEPs that serve both roles. so the idea would be to: 1) house current specs at packaging.python.org... basically a document tree that's organized by topic, not numbers and it's free of proposal rationales, historical discussion, and transition plans etc... 2) keep using the PEP process for adjusting or adding to the specs 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? --Marcus
well, if you look up in the thread, a few of us are saying it's not. It doesn't distinguish Current Specs vs Proposals very well.
How would you add that metadata to the version string (according to PEP
440)? Semver 3.0 (pbr) From http://docs.openstack.org/developer/pbr/semver.html : Example: 1.0.0.dev8 < 1.0.0.dev9 < 1.0.0.a1.dev3 < 1.0.0.a1 < 1.0.0.b2 < 1.0.0.c1 < 1.0.0
On Mon, Sep 7, 2015 at 1:13 PM, Marcus Smith
pulling this idea out of the "Linux wheel support" thread, since it deserves it's own thread...
the idea being that we should better distinguish: 1) the current packaging "Specs" (for metadata, versions, etc...) vs 2) Proposals to change them
currently, we just have PEPs that serve both roles.
so the idea would be to: 1) house current specs at packaging.python.org... basically a document tree that's organized by topic, not numbers and it's free of proposal rationales, historical discussion, and transition plans etc...
* https://packaging.python.org/en/latest/glossary.html#term-version-specifier -> pypa.io/en/latest/peps * https://www.pypa.io/en/latest/peps * https://github.com/pypa/pypa.io/blob/master/source/peps.rst
2) keep using the PEP process for adjusting or adding to the specs
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?
Tagged [semver 3.0 (+1)] versions can be managed *individually* with readthedocs. One old-school way to do this would be to e.g. write a conf.py and a sphinx adapter for PEPs: https://github.com/python/peps And copy/paste with version strings at the end of filenames
--Marcus
_______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org https://mail.python.org/mailman/listinfo/distutils-sig
so the idea would be to:
1) house current specs at packaging.python.org... basically a document tree that's organized by topic, not numbers and it's free of proposal rationales, historical discussion, and transition plans etc...
* https://packaging.python.org/en/latest/glossary.html#term-version-specifier -> pypa.io/en/latest/peps * https://www.pypa.io/en/latest/peps * https://github.com/pypa/pypa.io/blob/master/source/peps.rst
I can't make sense of how these links are a response to point #1? I wrote the PEP summary page you're linking me too, so I'm aware of it : ) This summary page is *not* the Specs idea. Maybe a picture is worth a thousand words here.... and will require a draft PR against the PyPUG to make it clear to everyone
2) keep using the PEP process for adjusting or adding to the specs
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?
Tagged [semver 3.0 (+1)] versions can be managed *individually* with readthedocs.
sorry, I don't follow your point.
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
participants (3)
-
Marcus Smith
-
Nick Coghlan
-
Wes Turner