classification
Title: PEP should note related PEPs
Type: enhancement Stage:
Components: Documentation Versions:
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: docs@python Nosy List: barry, brandon-rhodes, brett.cannon, docs@python, georg.brandl, ncoghlan, onelson, terry.reedy
Priority: normal Keywords:

Created on 2013-03-07 01:13 by brandon-rhodes, last changed 2013-03-11 13:46 by barry. This issue is now closed.

Messages (9)
msg183625 - (view) Author: Brandon Rhodes (brandon-rhodes) * Date: 2013-03-07 01:13
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.
msg183626 - (view) Author: Brandon Rhodes (brandon-rhodes) * Date: 2013-03-07 01:14
(Corrected "not" to "note" in the title and went with "enhancement")
msg183627 - (view) Author: Brandon Rhodes (brandon-rhodes) * Date: 2013-03-07 01:16
The original inspiration:

https://twitter.com/theomn/status/309468740611891200
msg183787 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-09 03:30
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.
msg183829 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2013-03-09 16:32
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. :)
msg183841 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-09 19:26
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.
msg183842 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-03-09 19:29
Re-reading the original post, I see that a section (or paragraph) was an option Brandon requested. Changed title to reflect remaining issue.
msg183943 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2013-03-11 08:08
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.
msg183961 - (view) Author: Barry A. Warsaw (barry) * (Python committer) Date: 2013-03-11 13:46
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. :)
History
Date User Action Args
2013-03-11 13:46:12barrysetstatus: open -> closed
resolution: wont fix
messages: + msg183961
2013-03-11 08:08:16ncoghlansetnosy: + ncoghlan
messages: + msg183943
2013-03-09 19:29:32terry.reedysetmessages: + msg183842
title: PEP should note if it has been superseded -> PEP should note related PEPs
2013-03-09 19:26:21terry.reedysetmessages: + msg183841
2013-03-09 16:32:21barrysetmessages: + msg183829
2013-03-09 03:30:42terry.reedysetnosy: + barry, brett.cannon, georg.brandl, terry.reedy
messages: + msg183787
2013-03-07 01:24:48onelsonsetnosy: + onelson
2013-03-07 01:16:11brandon-rhodessetmessages: + msg183627
2013-03-07 01:14:02brandon-rhodessettype: enhancement
messages: + msg183626
title: PEP should not if it has been superseded -> PEP should note if it has been superseded
2013-03-07 01:13:04brandon-rhodescreate