PEP 1: Revise, clarify and update language around python-dev, announcements and the discussion venue

[CAM-Gerlach]

Several different places in PEP 1 refer to the python-dev (and python-ideas) mailing list as the only canonical place to discuss PEPs, and requires SC approval for other discussion locations. Nowadays, the PEPs section of the Python Discourse is equally accepted and well used in practice by a number of PEPs, so it should be linked and mentioned therein as well. Likewise, distutils-sig is mentioned as the nominal location for packaging PEP discussion, when the Packaging section of the Python Discourse has been the de-facto location for several years now while distutils-sig sees little to no remaining traffic, and recently was formally switched over on the PyPA specs.

Therefore, I propose updating the PEP to link the Discourse section alongside the mailing list in the PEP, as well as linking directly to the mailing list's web portal for users to subscribe and view past discussions, and replacing references to distutils-sig with the Packaging section on the Python Discourse.

EDIT: Sorry, accidentally hit submit before I was done creating the issue.

[encukou]

AFAIK, each PEP should be announced on python-dev, but the main discussion can be anywhere else -- wherever the Discussions-To header points to. Typing PEPs are usually discussed on typing-sig, for another example.

[CAM-Gerlach]

Thanks; I can revise the PEP to that effect. In particular, the PEP also mentions that explicit SC approval is needed to have the official PEP discussion and resolution somewhere other than python-dev; should that statement be modified (e.g. to only be necessary for venues not hosted somewhere on Python.org), or removed?

[encukou]

Hm, I thought the official discussion/resolution can be notices like this and this. Those should stay on python-dev, as the one place you need to be subscribed to.
But I see the Discussions-To header is documented as pointing to the place the pronouncement will happen. I don't think it's being used that way.

[AA-Turner]

Hm, I thought the official discussion/resolution can be notices like this and this. Those should stay on python-dev, as the one place you need to be subscribed to.

This was my understanding -- substantive discussion can happen anywhere reasonable (typing-sig, asyncio-sig, web-sig, Discourse, etc seem to have been used), but announcements must go to python-dev, even if to note the PEP has been drafted and point to the forum for discussion.

But I see the Discussions-To header is documented as pointing to the place the pronouncement will happen. I don't think it's being used that way.

@CAM-Gerlach could you update this with the other changes? Of course it is the gift of the Council, but I imagine all pronouncements will make their way to python-dev, so that could be used as a sensible thing.

A

[CAM-Gerlach]

Hm, I thought the official discussion/resolution can be notices like this and this.

That was my understanding as well based on your previous reply (with the clarification that "discussion" refers to announcement of the discussion venue, as referred to in your initial reply), with the exception of packaging PEPs (due to their special SC delegation, for which the de jure and de-facto location is the Packaging section of the Discourse). I just included "and resolution" there because that was the text of the PEP, but it makes sense to clarify that (with SC approval).

I'll go ahead with a PR that the SC can review and (hopefully) approve, once its ready.

[warsaw]

PEP 1 also says:

Eventually, all Standards Track PEPs must be sent to the python-dev list for review as described in the next section.

I think what ultimate makes the most sense is that discussions can happen anywhere that is 1) appropriate for the topic; 2) publicly available so all interested parties can participate; 3) subject to the Python CoC. Discussions-To should point to the most specific place where those discussions are held, i.e. not just "Discourse" so that people who want to participate can easily find the place to participate. And finally, PEPs should at least be announced on python-dev, including announcements of significant updates. PEP 1 should clarify this policy. That way people should know exactly how to be informed of new feature discussions, can participate if interested, and won't be surprised by a pronouncement out of the blue.

[CAM-Gerlach]

3. subject to the Python CoC. Discussions-To should point to the most specific place where those discussions are held, i.e. not just "Discourse" so that people who want to participate can easily find the place to participate

Thanks for bringing this up! This in particular has been one of the biggest single pain points I've faced as a PEP reader. Very often, I'd be reading a draft PEP and wondered what the current status was, what discussion was happening on it and what the plan was for moving forward—or wanted to contribute feedback, input or help. Or I'd be trawling through an old PEP and wanted skim the discussions that shaped it, or try to figure out why a specific design decision was made.

However, many PEPs, even recent ones, don't have a link to a specific thread (either on python-dev, discourse or elsewhere) in the Discussions-To header, and rather just state [email protected], if list anything at all. This requires users interested to switch to their favorite search engine and search for the latest relevant thread and hope they find the right one, if they find anything at all, which makes this much more difficult than it needs to be.

As part of the aforementioned PR, the proposed revision will explicitly clarify that a direct link to the latest discussion thread, whatever the venue is, should always be provided, not just Discourse, python-dev or nothing at all, as the present language seemingly allows. I've also revised the title to clarify the somewhat more general scope of this issue, based on the discussion here.

[warsaw]

Yep. The nice thing is that now that python-dev is on Mailman 3, you can provide a really nice, stable link to the discussion thread for that topic.

[CAM-Gerlach]

As somewhat of a corollary, @brettcannon mentioned in a comment on #2335 that updated the Discussions-To link on PEP-0594 to point to the new discussion thread that

I actually left that link alone so someone could follow the complete discussion from beginning to end, but it isn't worth holding the PR up over.

Several commentators mentioned that it was useful to have the Discussions-To link point to the current active/latest thread (and have the OPs of the threads cross-link each other for continuity), but also recognized the value in linking the previous ones, so that interested readers could follow the complete discussion and maintain a record of them.

After some thought and testing, this could be easily achieved within the existing header framework and code by having PEP authors inline-link the dates in the Post-History field to their corresponding threads, which would make the field much more useful than just mentioning the dates the PEP was posted in some form to an unspecified venue, and rather actually link those threads. This requires minimal effort beyond the existing linking of them in the Discussions-To field (when a new thread is created, instead of just deleting the old Discussions-To link, it is instead moved to the newly added post date), and works just fine with no backend or linting changes while making the field serve a much more concrete and helpful purpose to authors, editors and readers alike.

@AA-Turner responded:

I'm maybe -0.5 on this, I think I'd need to be convinced some more, especially as some authors create new threads each time, some authors re-use the same thread, some authors post simultaneously to Discourse/Python-Dev/Typing-Sig/etc but may have a preference -- catering for all cases would be challenging.

There should be (and AFAIK, always is) a single canonical Discussions-To link/email list at any given time, such the official PEP discussion to be considered by the PEP-Delegate/SC occurs in a designated, cohesive and monitored location rather than scattered and disjointed on different threads and lists that may or may not be mentioned on the PEP or considered by those approving/rejecting it. Announcements may be posted to other lists/locations, but there is (or at least, should be) one canonical Discussions-To location at a given time, which may be updated if the PEP is re-posted due to significant changes or a long time elapsed.

The Post-History field, in turn, represents the times those threads (on Python-Dev, Typing-Sig, Discourse or whatever the chosen location is) were posted, and thus is the perfect place to link them, since there should be a 1:1 correspondence between post dates and official threads, and inline-linking them takes up no more visual space in the rendered output while being relatively clear to the reader what the links represent.

[CAM-Gerlach]

Note that the issues discussed here just came up in a Discourse post of PEP-0655, which is an illustrative case study of the issues and confusion these changes will help resolve, and perhaps provides insight on how we can further clarify this process for PEP authors.

TL;DR: Addressing this issue as we've discussed should resolve most if not all points of confusion, but it does raise one question—should we recommend/require that PEP authors also post an announcement on Discourse, in addition to Python-Dev and the Discussions-To thread (I'd think not nessesary, outside of special cases)? If so, how do we ensure it doesn't fragment discussion, to the detriment of both the SC/PEP-Delegates and the broader community (I'd suggest a clear disclaimer + link & possible thread lock)?

See the Details dropdown for the full analysis of the user's confusion and how this proposal does/can address it.

To summarize, the PEP author @davidfstr stated the PEP had previously been discussed on Typing-Sig, which I'm guessing they might mean this thread, as the thread isn't linked either under the Discussions-To in the PEP, elsewhere I can see in the body, nor in the post to Discourse). This is all well and good, of course, aside from the lack of a link anywhere to said discussion thread, which this issue will clarify PEP 1 to explicitly mention.

Secondly, the PEP author stated they'd posted it to Python-Dev (also unlinked) which appears to refer to this thread; this largely fulfills what was discussed here requiring an "announcement" on Python-Dev, though this again should be clarified (and will be by this proposal), as the author expressed some uncertainty over the process on said thread, they didn't know to make clear it was just an announcement and that canonical discussion should take place on the Discussions-To thread rather than split between multiple lists and venues, and they then seemed to be concerned about the lack of replies (which in fact was unknowingly appropriate), and posted the full, raw PEP text as a followup.

Finally, they then posted it on Discourse, again including the full, raw, PEP text (which was then further mangled by Discourse's rendering) instead just linking the actual PEP, without a link to the actual discussion thread or a clear indication that it was an announcement, and in the Core Development rather than the PEPs category. These are all things we can and will clarify here, these are related aspects we will want to explicitly clarify as part of this, since there is currently no guidance for PEP authors on this (despite the author taking the time to look for it in PEP 1) aside from informal suggestions from sponsors.

This does raise a key question (which would be particularly good to hear from @warsaw @encukou and @brettcannon on, due to their SC and PEP-Delegate experience)—should we recommend or require PEP authors to post an announcement of their PEPs to Discourse as well as Python-Dev and the Discussions-To location, if not either, presumably making clear that discussion should take place at the linked canonical Discussions-To thread to keep things in one place for both users and SC/PEP-Delegate reviewers (maybe even a locked thread?) I'd be concerned that without careful handling it would fragment discussion, add more overhead for PEP authors and isn't really that necessary on top of posting on the appropriate list (Typing-SIG) and as an announcement on Python-Dev, at least outside of special cases.

Since #2302 is merged and this appears to be a continuing source of confusion, I'll go ahead with this changes and clarifications discussed here for your review.

[CAM-Gerlach]

I opened #2346 that implements what I discuss in the OP, as modified/extended by @encukou 's, @warsaw 's and @AA-Turner 's requests as well as informed by the user case above. Please let me know what you think!

Also, I thought I posted this earlier, but to note, the PEP author also noted there that it wasn't clear from PEP 1 when a PEP should be submitted to the Steering Council for review, nor how to formally do so. Indeed, I don't really see anything explicit on this point in PEP 1. Furthermore, PEP 1's text doesn't really explicitly discuss the SC approval process at all; its language reads to imply that a PEP-Delegate is the "standard" way of approving a PEP, and if one is not found, the PEP will be marked "Deferred" rather than reviewed by the SC directly:

If no volunteer steps forward, then the Steering Council will approach core developers (and potentially other Python community members) with relevant expertise, in an attempt to identify a candidate that is willing to serve as PEP-Delegate for that PEP. If no suitable candidate can be found, then the PEP will be marked as Deferred until one is available.

The PR incidentally makes that clearer by way of updating the remaining outdated line about submitting to Python-Dev rather than the SC for final PEP content review (that I didn't directly address in #2257 or #2273 ), but I can open a followup issue to further update and clarify this to align with current practice, as needed.