Skip to content

PEP 1: Update to reflect best practices in PEP annoucement/discussion #2346

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Feb 22, 2022
Merged

PEP 1: Update to reflect best practices in PEP annoucement/discussion #2346

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 103 additions & 43 deletions pep-0001.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
(a.k.a. python-list@python.org mailing list) or the python-ideas@python.org
mailing list is the best way to go about this.
PEP-able. Posting to the `Python-Ideas`_ mailing list or the
`Ideas category`_ of the `Python Discourse`_ is usually
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
Expand All @@ -149,15 +151,16 @@ 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.


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),
Expand Down Expand Up @@ -242,37 +245,86 @@ 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`_.

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
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
`python-dev list <mailto:python-dev@python.org>`__ for review as described
in the next section.
same time.

Standards Track PEPs consist of two parts, a design document and a
reference implementation. It is generally recommended that at least a
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: and the to -> and to the

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks! I'll fix it in my forthcoming followup PR (see below).


If a PEP undergoes a significant re-write or other major, substantive
changes to its proposed specification, a new thread should typically be created
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: changes -> change

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
open-ended discussions on public mailing lists should be avoided.
Strategies to keep the discussions efficient include: setting up a
separate SIG mailing list for the topic, having the PEP author accept
private comments in the early design phases, setting up a wiki page, etc.
before submitting it for review. However, to avoid long-winded and
open-ended discussions, strategies such as soliciting private or more
narrowly-tailored feedback in the early design phase,
collaborating with other community members with expertise in the PEP's
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.
Comment on lines +314 to +316
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Earlier it was mentioned that the "designated thread" may need to be updated/changed over time. Thus links to the earlier threads will be lost in the latest version of the PEP document.

Is it likely the case that the SC will want to go back and read not just the lastest designated thread, but perhaps all prior such threads? If so, then perhaps the SC would find it useful to keep multiple threads in the Discussions-To field?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a great point (albeit not really a regression), and the plan to tackle it was by inline-linking each date in Post-History to that respective thread, making that field have a much clearer and more practically useful purpose following these changes. I almost included that change here as well, but since it was more purely technical in nature and a little out of the original scope, I decided to defer it to a followup PR once this one was in. I can open the followup PR with that change shortly, and include your other fixes as well.



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 of the PEP must be requested of the
core developers, usually via an email to the python-dev mailing list.
However, content review and acceptance of the PEP is ultimately the
responsibility of the Steering Council, which is formally initiated by
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
Expand Down Expand Up @@ -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
Expand All @@ -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".
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -543,15 +592,15 @@ 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>
* Content-Type: <text/x-rst | text/plain>
* 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>
Expand Down Expand Up @@ -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
python-dev, a Discussions-To header will indicate the mailing list
or URL where the pronouncement will occur. A temporary Discussions-To header
may also be used when a draft PEP is being discussed prior to submission for
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 Discussions-To header provides the URL to the current
canonical discussion thread for the PEP.
For email lists, this should be a direct link to the thread in the list's
archives, rather than just a mailto: or hyperlink to the list itself.

The Type header specifies the type of PEP: Standards Track,
Informational, or Process.
Expand All @@ -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
headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
versions of the PEP are posted to Python-Dev and/or the Discussions-To thread.
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.
Expand Down Expand Up @@ -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
=========
Expand Down
22 changes: 12 additions & 10 deletions pep-0012.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
and/or python-dev@python.org. If there is another mailing list or
public forum more appropriate for discussion of your new feature,
add a Discussions-To header right after the Author header. Most
Informational PEPs don't need a Discussions-To header.
- Add the direct URL of the PEP's canonical discussion thread
(on e.g. Python-Dev, Discourse, etc) under the Discussions-To header.
If the thread will be created after the PEP is submitted as an official
draft, it is okay to just list the venue name initially, but remember to
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".

Expand Down Expand Up @@ -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
the Discussions-To header above). If you posted your PEP to the lists
on August 14, 2001 and September 3, 2001, the Post-History header
would look like::
each time you post your PEP to the designated discussion forum (and announce
it on Python-Dev, if needed; see the ``Discussions-To`` header above).
If you posted threads for your PEP on August 14, 2001 and September 3, 2001,
the Post-History header would look like::

Post-History: 14-Aug-2001, 03-Sept-2001

Expand Down Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions pep-0012/pep-NNNN.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down