Allow adding a Discussions section instead of Post-History and Discussed-To headers

[vstinner]

PEP 1 and PEP 12 ask to add Post-History and Discussed-To headers to a PEP. Previously, Post-History was just a list of dates. Recently, it was enhanced to support links.

I propose to allow replacing these headers with a Discussions section at the end with free formatting. Advantages:

• Discussions are less important than the PEP itself and so IMO should be put at the end
• A whole section gives more place to add more details and so be more useful

This issue was discussed at #2544

See also #2490

[encukou]

I find Post-History (the new one with links) pretty convenient when reviewing the discussion.
I wouldn't mind an additional Discussions section, but I don't think I'd need the additional detail too often.

[warsaw]

The original reasons for the headers (as I remember them) was:

• Post-History: to ensure that the PEPs were actually being discussed in public forums
• Discussions-To: where a dev landing on the PEP would know to go to if they wanted to comment on the PEP

Given that there are so many places to discuss PEPs now, I'm not sure Post-History is really all that useful, but I think knowing where the "right" place to discuss the PEP is probably more important. A Discussions section at the end, which indeed might be useful, also maybe de-emphasizes too much the "where do I go to engage" question. I'm not saying a Discussions section isn't useful, just that I'm not sure it should replace Discussions-To. I'm fine with it effectively replacing Post-History though.

[AA-Turner]

Allowing a discussions section seems fine, and PEP authors may want to use it to summarise changes after discussions, etc (some PEPs currently have similar 'version' information).

We could automatically parse "Discussions-To" from the final "Post-History" header, but if consensus is that the former is more useful, we could suggest a writing a (short) narrative summary of discussion to PEP authors.

---

As an aside, I've found Post-History useful personally in the past for quickly finding links to discussions, but on PEPs that are controversial, complex, or have long histories, I feel a summary of the discussion would be of more immediate use than spending several hours reading through email archives and attempting to piece together a history after the fact. So I have sympathy for the proposed section, as long as we keep strong guidance to retain some link to archives of the discussion.

A

[vstinner]

I looked at the PEPs that I wrote or co-authored. In fact, I never added a Post-History header, I didn't know that it was required, "make" and CIs never complained. Examples:

• Links in "Discussion" and "References" sections: https://peps.python.org/pep-0674/#discussion
• "Post History" section: https://peps.python.org/pep-0670/#post-history -- the References section also contains links to discussions, especially the Discourse thread
• Links in the "Version History" section: https://peps.python.org/pep-0620/#version-history
• "Discussions" section: https://peps.python.org/pep-0587/#discussions (9 email threads)
• "Previous Discussions" section: https://peps.python.org/pep-0545/#previous-discussions
• "Post History" section: https://peps.python.org/pep-0540/#post-history
• "Discussion" section: https://peps.python.org/pep-0509/#discussion

There are links to python-dev and python-ideas threads, and issues at bugs.python.org.

[encukou]

CI can't complain about this, because when a new PEP is added it doesn't have Post-History.

[vstinner]

Ok, let's continue with Post-History.