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 python-dev@python.org, 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.