PEP 1: Update to reflect best practice in PEP annoucement and discussion (#2346)
This commit is contained in:
CAM Gerlach
GitHub
parent
14fd18da9f
commit
b1e81ac1dc
146
pep-0001.txt
146
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
|
||||
(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
|
||||
|
|
@ -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`_.
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
||||
|
||||
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
|
||||
|
|
@ -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
|
||||
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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
=========
|
||||
|
|
|
|||
22
pep-0012.rst
22
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
|
||||
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".
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
Loading…
Reference in New Issue