PEP 11: Add Discussions section

[vstinner]

No description provided.

[vstinner]

@brettcannon @corona10: Here is a PR to add references to recent discussions.

[vstinner]

I dislike Post-History header. IMO it's not well rendered, so hard to read, and the format disallow to add much info (discussion title, first author name, etc.). I prefer to omit the day, only mention the month+year.

[corona10]

Looks good to me, but let's wait Brett :)

[CAM-Gerlach]

Adding a section listing the discussions that led to the PEP and drove its evolution is great, of course, and what I also recommended in #2538 (although it would have been arguably been even more beneficial to provide a bit of context summarizing each discussions and mentioning what actually changed in the PEP because of them, beyond just repeating the thread name, date and author shown at the top of the linked page).

However, I'm afraid I don't quite understand why it was necessary to completely remove the existing Post-History, which has always been a required header per PEP 1 and PEP 12, and provides an at-a-glance, human- and machine-readable list of discussion thread dates, venues and links in a compact and consistent format.

I opened # to restore and update it, including the relevant direct links @vstinner helpfully dug up, while of course retaining the inline Discussions section at the bottom of the PEP as added here.

I dislike Post-History header.

Could you please open an issue articulating your specific concerns and what you propose changing ?

For reference, I implemented current format was requested on #2335 by multiple people, discussed and documented in #2266 and as a followup to PR #2346 , where it was also independently requested by another reviewer, discussed at length and implemented in #2358 , part of the changes approved by the Steering Council in python/steering-council#113 , part of the experimental public API added in #2475 , with the rendering further improved in #2467 and validation added in #2484 .

While a lot has gone into the current header rendering, there's always room to evolve further, of course. After all, if not for the constructive feedback of PEP authors and others, Post-History would still just be a static field with bare dates and nothing else.

it's not well rendered

Okay, so can you describe the specific problems you've found with the rendering so we can fix them?

so hard to read

Would you mind explaining what makes it hard to read, so we can improve it?

the format disallow to add much info (discussion title, first author name, etc.)

The Post-History header is intended to be a compact, chronological, at-a-glance list of the PEP's discussion threads; those interested can click the link to view that info at the top of the linked page, and authors are of course free (and encouraged) to link/describe related discussions in as much detail as they like in the body of the PEP. I in fact wanted to include that info automatically in the hover text, but it would either require a bunch of HTTP requests and HTML scraping every build, or make authors do a bunch of extra work manually duplicating the existing metadata, so it didn't seem like a good idea.

I prefer to omit the day, only mention the month+year.

The fact that the Post-History header is in a consistent, parsable syntax is what allows easily displaying/outputting any desired date format (e.g. ISO 8601/RFC 3339) with just a line or two of code and without touching any PEPs. In the body of the PEP, authors are of course free to follow their personal aesthetic preferences with any reasonably unambiguous date format they see fit.

[vstinner]

Why do you want to make it even harder to write a PEP? The formalism is already really high.

Post-History is a list of date: it doesn't mention on which list the message was sent, and it became really hard to find a message from a date in Mailman 3 which shows the date of the latest message, not the first message. Today, PEPs are discussed in many places:

• https://github.com/python/peps/
• https://discuss.python.org/
• python-ideas, python-dev and python-committers lists
• etc.

You cannot simply give a list of dates. If PEP 1 and PEP 12 disallow that, I suggest to fix these PEPs instead.

Before my change, the headers were:

PEP: 11
Title: CPython platform support
Version: $Revision$
Last-Modified: $Date$
Author: Martin von Löwis <martin@v.loewis.de>,
        Brett Cannon <brett@python.org>
Status: Active
Type: Process
Content-Type: text/x-rst
Created: 07-Jul-2002
Post-History: 18-Aug-2007,
              16-May-2014,
              20-Feb-2015

It doesn't say where the PEP was discussed. Did you try to find the related emails from these dates?

[JelleZijlstra]

We recently changed Post-History to allow links. See PEP-681 for an example. That format would work here too, though your PR adds some more useful detail, like the thread names.

[CAM-Gerlach]

@vstinner I think there may be a miscommunication between us, sorry, because I thought you were taking about the new format and automatic parsing I just implemented, and it sounds like you thought I was talking about the old format, but it sounds like we are in fact in violent agreement 😄

Just like you, for the same reasons you aptly describe, I also found it very hard to unambiguously find the right thread or message with just the date, making the legacy Post-History format not very useful. Therefore, as mentioned in my original comment on #2358 and discussed in my comment above, Post-History now allows and encourages the post dates dates to be normal reST links to the threads in question, which avoids those issues.

Additionally, now that I implemented #2467 , the posting venue and type (Python-Committers thread, Python-Dev message, Discourse post, etc) automatically displays on hover for any Python.org mailing list, archive, thread or message (Mailman/3/Pipermail/Hyperkitty), Discourse category, thread or message, or Google Groups list (ideally I'd have included the title and author too, but that would have required either HTTP requests or extra work for authors).

You can check out how this looks for this PEP in the source and in the output on #2546 . This also works for Discussions-To and Resolution automatically without any changes on your end; it generates descriptive link text from links, and for older PEPs without links, it even automatically generates those URLs themselves for Python.org (Mailman, Mailman3, Pipermail or Hyperkitty, as appropriate) and Google Groups list addresses.

It doesn't say where the PEP was discussed. Did you try to find the related emails from these dates?

Yeah, though thanks in large part to your harder work doing it already :D In fact, I was confused by the fact that the 2015 "post" originally listed under Post-History was actually just a specific message in an already linked thread; I don't know if I would have even found it at all if you hadn't.

[encukou]

Why do you want to make it even harder to write a PEP?

IMO, PEP editors are the ones interested in these details of keeping the PEPs organized (which increasingly includes automation as well, so human readers aren't the only audience). But it shouldn't be hard for the PEP author.
However, removing existing headers might be making their job harder

I suggest to fix these PEPs instead.

You can file an issue/PR with the proposal. But be prepared for some nitpicky discussion, and don't assume you know all the background.

[vstinner]

I don't think that a closed PR is a good place to discuss the "Discussions" section, so I created #2560 instead.