PEP 1: Update to reflect best practice in PEP annoucement and discussion (#2346)

pep-0001.txt

@@ -132,9 +132,11 @@ Each PEP must have a champion -- someone who writes the PEP using the style
 and format described below, shepherds the discussions in the appropriate
 forums, and attempts to build community consensus around the idea.  The PEP
 champion (a.k.a. Author) should first attempt to ascertain whether the idea is
-PEP-able.  Posting to the comp.lang.python newsgroup
+PEP-able.  Posting to the `Python-Ideas`_ mailing list or the
-(a.k.a. python-list@python.org mailing list) or the python-ideas@python.org
+`Ideas category`_ of the `Python Discourse`_ is usually
-mailing list is the best way to go about this.
+the best way to go about this, unless a more specialized venue is appropriate,
+such as `Typing-SIG`_ for static typing or the `Packaging category`_ of the
+Python Discourse for packaging issues.
 
 Vetting an idea publicly before going as far as writing a PEP is meant
 to save the potential author time. Many ideas have been brought
@@ -149,7 +151,8 @@ mean it will work for most people in most areas where Python is used.
 
 Once the champion has asked the Python community as to whether an
 idea has any chance of acceptance, a draft PEP should be presented to
-python-ideas.  This gives the author a chance to flesh out the draft
+the appropriate venue mentioned above.
+This gives the author a chance to flesh out the draft
 PEP to make properly formatted, of high quality, and to address
 initial concerns about the proposal.
 
@@ -157,7 +160,7 @@ initial concerns about the proposal.
 Submitting a PEP
 ----------------
 
-Following a discussion on python-ideas, the workflow varies based on whether
+Following the above initial discussion, the workflow varies based on whether
 any of the PEP's co-authors are core developers. If one or more of the PEP's
 co-authors are core developers, they are responsible for following the process
 outlined below. Otherwise (i.e. none of the co-authors are core developers),
@@ -242,13 +245,9 @@ on GitHub.
 
 As updates are necessary, the PEP author can check in new versions if they
 (or a collaborating developer) have write access to the `PEP repository`_.
-
+Getting a PEP number assigned early can be useful for ease of
-After a PEP number has been assigned, a draft PEP may be discussed further on
-python-ideas (getting a PEP number assigned early can be useful for ease of
 reference, especially when multiple draft PEPs are being considered at the
-same time). Eventually, all Standards Track PEPs must  be sent to the
+same time.
-`python-dev list <mailto:python-dev@python.org>`__ for review as described
-in the next section.
 
 Standards Track PEPs consist of two parts, a design document and a
 reference implementation.  It is generally recommended that at least a
@@ -256,23 +255,76 @@ prototype implementation be co-developed with the PEP, as ideas that sound
 good in principle sometimes turn out to be impractical when subjected to the
 test of implementation.
 
+
+Discussing a PEP
+----------------
+
+As soon as a PEP number has been assigned
+and the draft PEP is committed to the `PEP repository`_,
+a discussion thread for the PEP should be created
+to provide a central place to discuss and review its contents, and the
+PEP should be updated so that the ``Discussions-To`` header links to it.
+
+The PEP authors (or sponsor, if applicable) may select any reasonable venue
+for the discussion, so long as the the following criteria are met:
+
+* The forum is appropriate to the PEP's topic.
+* The thread is publicly available on the web so that all interested parties
+  can participate.
+* The discussion is subject to the `Python Community Code of Conduct
+  <https://www.python.org/psf/conduct/>`_.
+* A direct link to the current discussion thread is provided in the PEP
+  under the ``Discussions-To`` header.
+
+Typically, the `Python-Dev`_ mailing list and the
+`PEPs category`_ of the `Python Discourse`_ are good choices for most PEPs,
+while some specialized topics have specific venues, such as
+`Typing-SIG`_ for typing PEPs or the `Packaging category`_ on the Python
+Discourse for packaging PEPs. If the PEP authors are unsure of the best venue,
+the PEP Sponsor and PEP editors can advise them accordingly.
+
+If the chosen venue is not the `Python-Dev`_ mailing list,
+a brief announcement should be posted there when the draft PEP is
+committed to the PEP repository and available on the PEP website,
+with a link to the rendered PEP and the to canonical Discussions-To thread.
+
+If a PEP undergoes a significant re-write or other major, substantive
+changes to its proposed specification, a new thread should typically be created
+in the chosen venue to solicit additional feedback. If this occurs, the
+``Discussions-To`` link and ``Post-History`` in the PEP must be updated to
+reflect this new thread, and (if not the discussion venue) a further
+announcement sent to `Python-Dev`_ containing the same information as above
+and at least briefly summarizing the major changes.
+
 PEP authors are responsible for collecting community feedback on a PEP
-before submitting it for review. However, wherever possible, long
+before submitting it for review. However, to avoid long-winded and
-open-ended discussions on public mailing lists should be avoided.
+open-ended discussions, strategies such as soliciting private or more
-Strategies to keep the discussions efficient include: setting up a
+narrowly-tailored feedback in the early design phase,
-separate SIG mailing list for the topic, having the PEP author accept
+collaborating with other community members with expertise in the PEP's
-private comments in the early design phases, setting up a wiki page, etc.
+subject matter, and picking an appropriately-specialized discussion for the
+PEP's topic (if applicable) should be considered.
 PEP authors should use their discretion here.
 
+Once the PEP is assigned a number and committed to the PEP repository,
+substantive issues should generally be discussed on the canonical public
+thread, as opposed to private channels, GitHub pull request reviews or
+unrelated venues. This ensures everyone can follow and contribute,
+avoids fragmenting the discussion,
+and makes sure it is fully considered as part of the PEP review process.
+Comments, support, concerns and other feedback on this designated thread
+are a critical part of what the Steering Council or PEP-Delegate will
+consider when reviewing the PEP.
+
 
 PEP Review & Resolution
 -----------------------
 
 Once the authors have completed a PEP, they may request a review for
 style and consistency from the PEP editors.
-
+However, content review and acceptance of the PEP is ultimately the
-However, content review of the PEP must be requested of the
+responsibility of the Steering Council, which is formally initiated by
-core developers, usually via an email to the python-dev mailing list.
+opening a `Steering Council issue`_ once the authors (and sponsor, if any)
+determine the PEP is ready for final review and resolution.
 
 To expedite the process in selected cases (e.g. when a change is clearly
 beneficial and ready to be accepted, but the PEP hasn't been formally submitted
@@ -325,13 +377,6 @@ replacement can be found). In the event that a PEP-Delegate is asked to step
 down, this will overrule any prior acceptance or rejection of the PEP, and it
 will revert to Draft status.
 
-With the approval of the Steering Council, PEP review and resolution may also
-occur on a list other than python-dev (for example, distutils-sig for packaging
-related PEPs that don't immediately affect the standard library). In these
-cases, the "Discussions-To" heading in the PEP will identify the appropriate
-alternative list where discussion, review and pronouncement on the PEP will
-occur.
-
 When such standing delegations are put in place, the Steering Council will
 maintain sufficient public records to allow subsequent Councils, the core
 developers, and the wider Python community to understand the delegations that
@@ -348,6 +393,9 @@ the interpreter unduly.  Finally, a proposed enhancement must be
 the Steering Council.  This logic is intentionally circular.)  See :pep:`2`
 for standard library module acceptance criteria.
 
+Except where otherwise approved by the Steering Council, pronouncements
+of PEP resolution will be posted to the `Python-Dev`_ mailing list.
+
 Once a PEP has been accepted, the reference implementation must be
 completed.  When the reference implementation is complete and incorporated
 into the main source code repository, the status will be changed to "Final".
@@ -379,9 +427,10 @@ themselves has decided that the PEP is actually a bad idea, or has
 accepted that a competing proposal is a better alternative.
 
 When a PEP is Accepted, Rejected or Withdrawn, the PEP should be updated
-accordingly. In addition to updating the status field, at the very least
+accordingly. In addition to updating the Status field, at the very least
 the Resolution header should be added with a link to the relevant post
-in the python-dev mailing list archives.
+in the `Python-Dev`_ mailing list
+`archives <https://mail.python.org/archives/list/python-dev@python.org/>`_.
 
 PEPs can also be superseded by a different PEP, rendering the original
 obsolete.  This is intended for Informational PEPs, where version 2 of
@@ -543,7 +592,7 @@ optional and are described below.  All other headers are required.
     Author: <list of authors' real names and optionally, email addrs>
   * Sponsor: <real name of sponsor>
   * PEP-Delegate: <PEP delegate's real name>
-  * Discussions-To: <email address or URL>
+    Discussions-To: <URL of current canonical discussion thread>
     Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
              Withdrawn | Final | Superseded>
     Type: <Standards Track | Informational | Process>
@@ -551,7 +600,7 @@ optional and are described below.  All other headers are required.
   * Requires: <pep numbers>
     Created: <date created on, in dd-mmm-yyyy format>
   * Python-Version: <version number>
-    Post-History: <dates of postings to python-ideas and/or python-dev>
+    Post-History: <dates of postings to Python-Dev and/or the Discussions-To thread, in dd-mmm-yyyy format>
   * Replaces: <pep number>
   * Superseded-By: <pep number>
   * Resolution: <url>
@@ -588,16 +637,13 @@ limitation in the email address masking for reStructuredText PEPs)
 
 *Note: The Resolution header is required for Standards Track PEPs
 only.  It contains a URL that should point to an email message or
-other web resource where the pronouncement about the PEP is made.*
+other web resource where the pronouncement about
+(i.e. approval or rejection of) the PEP is made.*
 
-For a PEP where final pronouncement will be made on a list other than
+The Discussions-To header provides the URL to the current
-python-dev, a Discussions-To header will indicate the mailing list
+canonical discussion thread for the PEP.
-or URL where the pronouncement will occur. A temporary Discussions-To header
+For email lists, this should be a direct link to the thread in the list's
-may also be used when a draft PEP is being discussed prior to submission for
+archives, rather than just a mailto: or hyperlink to the list itself.
-pronouncement. No Discussions-To header is necessary if the PEP is being
-discussed privately with the author, or on the python-list, python-ideas
-or python-dev mailing lists.  Note that email addresses in the
-Discussions-To header will not be obscured.
 
 The Type header specifies the type of PEP: Standards Track,
 Informational, or Process.
@@ -611,8 +657,8 @@ Content-Type header is present.
 
 The Created header records the date that the PEP was assigned a
 number, while Post-History is used to record the dates of when new
-versions of the PEP are posted to python-ideas and/or python-dev.  Both
+versions of the PEP are posted to Python-Dev and/or the Discussions-To thread.
-headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+Both headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
 
 Standards Track PEPs will typically have a Python-Version header which
 indicates the version of Python that the feature will be released with.
@@ -803,12 +849,26 @@ Footnotes
 
 .. _PEP repository: https://github.com/python/peps
 
-.. _`GitHub pull request`: https://github.com/python/peps/pulls
+.. _GitHub pull request: https://github.com/python/peps/pulls
 
-.. _`GitHub issue`: https://github.com/python/peps/issues
+.. _GitHub issue: https://github.com/python/peps/issues
 
 .. _Steering Council issue: https://github.com/python/steering-council/issues/new/choose
 
+.. _Python-Ideas: https://mail.python.org/mailman3/lists/python-ideas.python.org/
+
+.. _Python-Dev: https://mail.python.org/mailman3/lists/python-dev.python.org/
+
+.. _Python Discourse: https://discuss.python.org/
+
+.. _Ideas category: https://discuss.python.org/c/ideas/
+
+.. _PEPs category: https://discuss.python.org/c/peps/
+
+.. _Typing-SIG: https://mail.python.org/mailman3/lists/typing-sig.python.org/
+
+.. _Packaging category: https://discuss.python.org/c/packaging/
+
 
 Copyright
 =========

pep-0012.rst

@@ -81,11 +81,13 @@ directions below.
 - If none of the authors are Python core developers, include a Sponsor
   header with the name of the core developer sponsoring your PEP.
 
-- For many PEPs, discussions will take place on python-ideas@python.org
+- Add the direct URL of the PEP's canonical discussion thread
-  and/or python-dev@python.org. If there is another mailing list or
+  (on e.g. Python-Dev, Discourse, etc) under the Discussions-To header.
-  public forum more appropriate for discussion of your new feature,
+  If the thread will be created after the PEP is submitted as an official
-  add a Discussions-To header right after the Author header. Most
+  draft, it is okay to just list the venue name initially, but remember to
-  Informational PEPs don't need a Discussions-To header.
+  update the PEP with the URL as soon as the PEP is successfully merged
+  to the PEPs repository and you create the corresponding discussion thread.
+  See :pep:`PEP 1 <1#discussing-a-pep>` for more details.
 
 - Change the Status header to "Draft".
 
@@ -116,10 +118,10 @@ directions below.
       Python-Version: 2.2
 
 - Leave Post-History alone for now; you'll add dates to this header
-  each time you post your PEP to the designated discussion forum (see
+  each time you post your PEP to the designated discussion forum (and announce
-  the Discussions-To header above). If you posted your PEP to the lists
+  it on Python-Dev, if needed; see the ``Discussions-To`` header above).
-  on August 14, 2001 and September 3, 2001, the Post-History header
+  If you posted threads for your PEP on August 14, 2001 and September 3, 2001,
-  would look like::
+  the Post-History header would look like::
 
       Post-History: 14-Aug-2001, 03-Sept-2001
 
@@ -157,7 +159,7 @@ your PEP)::
   Author: [Full Name <email at example.com>]
   Sponsor: *[Full Name <email at example.com>]
   PEP-Delegate:
-  Discussions-To: *[...]
+  Discussions-To: [URL]
   Status: Draft
   Type: [Standards Track | Informational | Process]
   Content-Type: text/x-rst

pep-0012/pep-NNNN.rst

@@ -3,13 +3,13 @@ Title: <REQUIRED: pep title>
 Author: <REQUIRED: list of authors' real names and optionally, email addrs>
 Sponsor: <real name of sponsor>
 PEP-Delegate: <PEP delegate's real name>
-Discussions-To: <email address or URL>
+Discussions-To: <REQUIRED: URL of current canonical discussion thread>
 Status: <REQUIRED: Draft | Active | Accepted | Provisional | Deferred | Rejected | Withdrawn | Final | Superseded>
 Type: <REQUIRED: Standards Track | Informational | Process>
 Requires: <pep numbers>
 Created: <date created on, in dd-mmm-yyyy format>
 Python-Version: <version number>
-Post-History: <REQUIRED: dates of postings to python-ideas and/or python-dev, in dd-mmm-yyyy format>
+Post-History: <REQUIRED: dates of postings to Python-Dev and/or the Discussions-To thread, in dd-mmm-yyyy format>
 Replaces: <pep number>
 Superseded-By: <pep number>
 Resolution: <url>