[issue17370] PEP should not if it has been superseded
New submission from Brandon Craig Rhodes: A friend (@theomn on Twitter) was just working off of PEP-333 when I mentioned to him that PEP-3333, and he had never heard of it, and he expressed the wish that PEPs would have a banner or something at the top if there is a more recent version of them. I think his idea is great, and is like the feature of PyPI where if Google lands you on an old version of a package then it is careful to tell you up at the top that a more recent version is available. This could extend to all sorts of cross-references that we should maintain: some PEPs have been superseded; others have more recent supplements that people should read as well (think of the relationship between packaging PEPs); PEPs that did not wind up being implemented have cousins who were; and so forth. Is this something that needs to wait until the New Python Web Site appears, and that would be meta-markup somehow maintained along with the PEP texts themselves? Or should there be a “Related PEPs” paragraph that we open at the top of each relevant PEP and just include the cross-links as raw updates to the PEP's own restructured text? I'm open to a simple implementation here, so long as we can provide more “community context” when people land on a PEP. ---------- assignee: docs@python components: Documentation messages: 183625 nosy: brandon-rhodes, docs@python priority: normal severity: normal status: open title: PEP should not if it has been superseded _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Brandon Craig Rhodes added the comment: (Corrected "not" to "note" in the title and went with "enhancement") ---------- title: PEP should not if it has been superseded -> PEP should note if it has been superseded type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Brandon Craig Rhodes added the comment: The original inspiration: https://twitter.com/theomn/status/309468740611891200 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Changes by Owen Nelson <onelson@gmail.com>: ---------- nosy: +Owen.Nelson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Terry J. Reedy added the comment: I think you are, in effect, asking for expansion of the 'PEP Header Preamble' section of PEP-0001. I have added some of the PEP editors listed in the PEP as nosy. I will let them decide if this should be discussed elsewhere. ---------- nosy: +barry, brett.cannon, georg.brandl, terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Barry A. Warsaw added the comment: On Mar 09, 2013, at 03:30 AM, Terry J. Reedy wrote:
I think you are, in effect, asking for expansion of the 'PEP Header Preamble' section of PEP-0001. I have added some of the PEP editors listed in the PEP as nosy. I will let them decide if this should be discussed elsewhere.
Looks like Benjamin just changed Replaced-By with Superseded-By in PEP 1 and Replaced with Superseded as a Status. He also updated a bunch of PEPs with the new headers, including 333. He probably should have discussed this with the other PEP editors beforehand, but in retrospect, it seems fine. I guess that means you're requesting a new header such as 'Related' which would contain a list of PEP numbers? Usually we just put those in the references (and it's perfectly fine to update a PEP after it's final with new references - that's why we have a version control system. :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Terry J. Reedy added the comment: I think an optional section header, "Related PEPs", to go either at the top or bottom (the two places of most prominence) whould be better than a header with a list of numbers. A section could have a sentence or two for each listing describing the perceived relation. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Terry J. Reedy added the comment: Re-reading the original post, I see that a section (or paragraph) was an option Brandon requested. Changed title to reflect remaining issue. ---------- title: PEP should note if it has been superseded -> PEP should note related PEPs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Nick Coghlan added the comment: Yeah, I think the problem in this case is specific to the multi-versioned PEPs like the WSGI reference and the metadata standards. In that case, a separate section in the document itself seems more appropriate than a generic header field. We should consider a similar section for PEP 302 (pointing to the 3.3 language reference) given the length of time that PEP has been the only systematic documentation for the import hooks. ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
Barry A. Warsaw added the comment: It seems to me that the right thing to add a related PEPs section to any PEP which needs it, but I don't think we need an official header for it. Thus, I'm closing this PEP as Won't Fix. Feel free to open new bugs for any specific PEP that needs additional work, or if you have commit privileges, JFDI. :) ---------- resolution: -> wont fix status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue17370> _______________________________________
participants (5)
-
Barry A. Warsaw -
Brandon Craig Rhodes
-
Nick Coghlan
-
Owen Nelson
-
Terry J. Reedy