Address Barry's comments and make a couple of other cleanups

This commit is contained in:
Nick Coghlan 2012-05-06 15:36:37 +10:00
parent a3d8f902ed
commit d9da11501a
1 changed files with 55 additions and 17 deletions

View File

@ -19,7 +19,7 @@ a new feature for Python or its processes or environment. The PEP
should provide a concise technical specification of the feature and a should provide a concise technical specification of the feature and a
rationale for the feature. rationale for the feature.
We intend PEPs to be the primary mechanisms for proposing new We intend PEPs to be the primary mechanisms for proposing major new
features, for collecting community input on an issue, and for features, for collecting community input on an issue, and for
documenting the design decisions that have gone into Python. The PEP documenting the design decisions that have gone into Python. The PEP
author is responsible for building consensus within the community and author is responsible for building consensus within the community and
@ -60,6 +60,16 @@ There are three kinds of PEP:
PEP Work Flow PEP Work Flow
============= =============
Python's BDFL
-------------
There are several reference in this PEP to the "BDFL". This acronym stands
for "Benevolent Dictator for Life" and refers to Guido van Rossum, the
original creator of, and the final design authority for, the Python
programming language.
Submitting a PEP Submitting a PEP
---------------- ----------------
@ -108,24 +118,29 @@ draft must be written in PEP style as described below, else it will be
sent back without further regard until proper formatting rules are sent back without further regard until proper formatting rules are
followed. followed.
If the PEP editor approves, he will assign the PEP a number, label it If the PEP editor approves, they will assign the PEP a number, label it
as Standards Track, Informational, or Process, give it status "Draft", as Standards Track, Informational, or Process, give it status "Draft",
and create and check-in the initial draft of the PEP. The PEP editor and create and check-in the initial draft of the PEP. The PEP editor
will not unreasonably deny a PEP. Reasons for denying PEP status will not unreasonably deny a PEP. Reasons for denying PEP status
include duplication of effort, being technically unsound, not include duplication of effort, being technically unsound, not
providing proper motivation or addressing backwards compatibility, or providing proper motivation or addressing backwards compatibility, or
not in keeping with the Python philosophy. The BDFL (Benevolent not in keeping with the Python philosophy. The BDFL can be consulted
Dictator for Life, Guido van Rossum) can be consulted during the during the approval phase, and is the final arbiter of the draft's
approval phase, and is the final arbiter of the draft's PEP-ability. PEP-ability.
Developers with commit privileges for the `PEP repository`_ may claim Developers with hg push privileges for the `PEP repository`_ may claim
PEP numbers directly by creating and committing a new PEP. When doing so, PEP numbers directly by creating and committing a new PEP. When doing so,
the developer must handle the tasks that would normally be taken care of by the developer must handle the tasks that would normally be taken care of by
the PEP editors (see `PEP Editor Responsibilities & Workflow`_). the PEP editors (see `PEP Editor Responsibilities & Workflow`_). This
includes ensuring the initial version meets the expected standards for
submitting a PEP. Alternately, even developers may choose to submit PEPs
through the PEP editors. When doing so, let the PEP editors know you have
hg push privileges and they can guide you through the process of updating
the PEP repository directly.
As updates are necessary, the PEP author can check in new versions if As updates are necessary, the PEP author can check in new versions if
they have hg push privileges, or can email new PEP versions to they have hg push privileges, or can email new PEP versions to
the PEP editor for committing. the PEP editors for publication.
Standards Track PEPs consist of two parts, a design document and a Standards Track PEPs consist of two parts, a design document and a
reference implementation. The PEP should be reviewed and accepted reference implementation. The PEP should be reviewed and accepted
@ -142,10 +157,11 @@ 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. private comments in the early design phases, setting up a wiki page, etc.
PEP authors should use their discretion here. PEP authors should use their discretion here.
PEP Review & Resolution PEP Review & Resolution
----------------------- -----------------------
Once the authors have completed a PEP, they must inform the PEP editor Once the authors have completed a PEP, they must inform the PEP editors
that it is ready for review. PEPs are reviewed by the BDFL and his that it is ready for review. PEPs are reviewed by the BDFL and his
chosen consultants, who may accept or reject a PEP or send it back to chosen consultants, who may accept or reject a PEP or send it back to
the author(s) for revision. For a PEP that is pre-determined to be the author(s) for revision. For a PEP that is pre-determined to be
@ -157,12 +173,16 @@ revisions.
The final authority for PEP approval is the BDFL. However, whenever a new The final authority for PEP approval is the BDFL. However, whenever a new
PEP is put forward, any core developer that believes they are suitably PEP is put forward, any core developer that believes they are suitably
experienced to make the final decision on that PEP may offer to serve as experienced to make the final decision on that PEP may offer to serve as
the "PEP czar" for that PEP. If their self-nomination is accepted by the the BDFL's delegate (or "PEP czar") for that PEP. If their self-nomination
other core developers and the BDFL, then they will have the authority to is accepted by the other core developers and the BDFL, then they will have
approve (or reject) that PEP. This process happens most frequently with PEPs the authority to approve (or reject) that PEP. This process happens most
where the BDFL has granted in principle approval for *something* to be done, frequently with PEPs where the BDFL has granted in principle approval for
but there are details that need to be worked out before the PEP can be *something* to be done, but there are details that need to be worked out
accepted. before the PEP can be accepted.
If the final decision on a PEP is to be made by a delegate rather than
directly by the BDFL, this will be recorded by including the
"BDFL-Delegate" header in the PEP.
For a PEP to be accepted it must meet certain minimum criteria. It For a PEP to be accepted it must meet certain minimum criteria. It
must be a clear and complete description of the proposed enhancement. must be a clear and complete description of the proposed enhancement.
@ -206,6 +226,20 @@ Some Informational and Process PEPs may also have a status of "Active"
if they are never meant to be completed. E.g. PEP 1 (this PEP). if they are never meant to be completed. E.g. PEP 1 (this PEP).
PEP Maintenance
---------------
In general, Standards track PEPs are no longer modified after they have
reached the Final state. Once a PEP has been completed, the Language and
Standard Library References become the formal documentation of the expected
behaviour.
Informational and Process PEPs may be updated over time to reflect changes
to development practices and other details. The precise process followed in
these cases will depend on the nature and purpose of the PEP being updated.
What belongs in a successful PEP? What belongs in a successful PEP?
================================= =================================
@ -307,6 +341,7 @@ optional and are described below. All other headers are required. ::
Post-History: <dates of postings to python-list and python-dev> Post-History: <dates of postings to python-list and python-dev>
* Replaces: <pep number> * Replaces: <pep number>
* Superseded-By: <pep number> * Superseded-By: <pep number>
* BDFL-Delegate: <PEP czar's real name and email address>
* Resolution: <url> * Resolution: <url>
The Author header lists the names, and optionally the email addresses The Author header lists the names, and optionally the email addresses
@ -329,6 +364,9 @@ following RFC 2822 continuation line conventions. Note that personal
email addresses in PEPs will be obscured as a defense against spam email addresses in PEPs will be obscured as a defense against spam
harvesters. harvesters.
The BDFL-Delegate field is used to record cases where the final decision to
approve or reject a PEP rests with someone other than the BDFL.
*Note: The Resolution header is required for Standards Track PEPs *Note: The Resolution header is required for Standards Track PEPs
only. It contains a URL that should point to an email message or 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 the PEP is made.*
@ -337,8 +375,8 @@ While a PEP is in private discussions (usually during the initial
Draft phase), a Discussions-To header will indicate the mailing list Draft phase), a Discussions-To header will indicate the mailing list
or URL where the PEP is being discussed. No Discussions-To header is or URL where the PEP is being discussed. No Discussions-To header is
necessary if the PEP is being discussed privately with the author, or necessary if the PEP is being discussed privately with the author, or
on the python-list or python-dev email mailing lists. Note that email on the python-list, python-ideas or python-dev email mailing lists. Note
addresses in the Discussions-To header will not be obscured. that email addresses in the Discussions-To header will not be obscured.
The Type header specifies the type of PEP: Standards Track, The Type header specifies the type of PEP: Standards Track,
Informational, or Process. Informational, or Process.