Further updates to PEP 1 to better reflect current practice

- identify the current PEP editors and clarify their role
- separate out PEP administrative email from design discussion
- reference implementations typically co-evolve with their PEP
- it's OK to get a PEP number before a PEP is ready for python-dev
- eliminate most of the ambiguous 'we' references

(Initial patch by Chris Jerdonek)
This commit is contained in:
Nick Coghlan 2012-12-22 21:30:14 +10:00
parent 85cdc32db3
commit 2af18441e8
2 changed files with 88 additions and 59 deletions

View File

@ -57,8 +57,8 @@ There are three kinds of PEP:
Any meta-PEP is also considered a Process PEP.
PEP Work Flow
=============
PEP Workflow
============
Python's BDFL
@ -70,19 +70,38 @@ original creator of, and the final design authority for, the Python
programming language.
PEP Editors
-----------
The PEP editors are individuals responsible for managing the administrative
and editorial aspects of the PEP workflow (e.g. assigning PEP numbers and
changing their status). See `PEP Editor Responsibilities & Workflow`_ for
details. The current editors are:
* Anthony Baxter
* Georg Brandl
* Brett Cannon
* David Goodger
* Jesse Noller
* Guido van Rossum
* Barry Warsaw
PEP editorship is by invitation of the current editors. The address
<peps@python.org> is a mailing list consisting of PEP editors. All
email related to PEP administration (such as requesting a PEP number
or providing an updated version of a PEP for posting) should be sent to
this address (no cross-posting please).
Submitting a PEP
----------------
The PEP editors assign PEP numbers and change their status. Please send
all PEP-related email to <peps@python.org> (no cross-posting please).
Also see `PEP Editor Responsibilities & Workflow`_ below.
The PEP process begins with a new idea for Python. It is highly
recommended that a single PEP contain a single key proposal or new
idea. Small enhancements or patches often don't need
a PEP and can be injected into the Python development work flow with a
a PEP and can be injected into the Python development workflow with a
patch submission to the Python `issue tracker`_. The more focused the
PEP, the more successful it tends to be. The PEP editor reserves the
PEP, the more successful it tends to be. The PEP editors reserve the
right to reject PEP proposals if they appear too unfocused or too
broad. If in doubt, split your PEP into several well-focused ones.
@ -111,16 +130,15 @@ python-ideas. 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.
Following a discussion on python-ideas, the proposal should be sent to
the `python-dev list <mailto:python-dev@python.org>`__ with the draft
PEP and the PEP editors <peps@python.org>. This
draft must be written in PEP style as described below, else it will be
sent back without further regard until proper formatting rules are
followed.
Following a discussion on python-ideas, the proposal should be sent as a
draft PEP to the PEP editors <peps@python.org>. The draft must be written
in PEP style as described below, else it will be sent back without further
regard until proper formatting rules are followed (although minor errors
will be corrected by the editors).
If the PEP editor approves, they will assign the PEP a number, label it
If the PEP editors approve, they will assign the PEP a number, label it
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 editors
will not unreasonably deny a PEP. Reasons for denying PEP status
include duplication of effort, being technically unsound, not
providing proper motivation or addressing backwards compatibility, or
@ -138,21 +156,27 @@ 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
they have hg push privileges, or can email new PEP versions to
the PEP editors for publication.
As updates are necessary, the PEP author can check in new versions if they
(or a collaborating developer) have hg push privileges, or else they can
email new PEP versions to the PEP editors for publication.
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
`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. The PEP should be reviewed and accepted
before a reference implementation is begun, unless a reference
implementation will aid people in studying the PEP. Standards Track
PEPs must include an implementation -- in the form of code, a patch,
or a URL to same -- before it can be considered Final.
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.
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
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.
PEP authors should use their discretion here.
@ -200,9 +224,9 @@ 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".
A PEP can also be assigned status "Deferred". The PEP author or
A PEP can also be assigned status "Deferred". The PEP author or an
editor can assign the PEP this status when no progress is being made
on the PEP. Once a PEP is deferred, the PEP editor can re-assign it
on the PEP. Once a PEP is deferred, a PEP editor can re-assign it
to draft status.
A PEP can also be "Rejected". Perhaps after all is said and done it
@ -262,8 +286,8 @@ Each PEP should have the following parts:
4. Specification -- The technical specification should describe the
syntax and semantics of any new language feature. The
specification should be detailed enough to allow competing,
interoperable implementations for any of the current Python
platforms (CPython, Jython, Python .NET).
interoperable implementations for at least the current major Python
platforms (CPython, Jython, IronPython, PyPy).
5. Motivation -- The motivation is critical for PEPs that want to
change the Python language. It should clearly explain why the
@ -290,9 +314,11 @@ Each PEP should have the following parts:
8. Reference Implementation -- The reference implementation must be
completed before any PEP is given status "Final", but it need not
be completed before the PEP is accepted. It is better to finish
the specification and rationale first and reach consensus on it
before writing code.
be completed before the PEP is accepted. While there is merit
to the approach of reaching consensus on the specification and
rationale before writing code, the principle of "rough consensus
and running code" is still useful when it comes to resolving many
discussions of API details.
The final implementation must include test code and documentation
appropriate for either the Python language reference or the
@ -429,12 +455,12 @@ of the PEP, it's probably best to send your comments and changes
directly to the PEP author. For more mature, or finished PEPs you may
want to submit corrections to the Python `issue tracker`_ so that your
changes don't get lost. If the PEP author is a Python developer, assign the
bug/patch to him, otherwise assign it to the PEP editor.
bug/patch to them, otherwise assign it to a PEP editor.
When in doubt about where to send your changes, please check first
with the PEP author and/or PEP editor.
with the PEP author and/or a PEP editor.
PEP authors who are also Python committers can update the
PEP authors with hg push privileges for the PEP repository can update the
PEPs themselves by using "hg push" to submit their changes.
@ -442,20 +468,21 @@ Transferring PEP Ownership
==========================
It occasionally becomes necessary to transfer ownership of PEPs to a
new champion. In general, we'd like to retain the original author as
new champion. In general, it is preferable to retain the original author as
a co-author of the transferred PEP, but that's really up to the
original author. A good reason to transfer ownership is because the
original author no longer has the time or interest in updating it or
following through with the PEP process, or has fallen off the face of
the 'net (i.e. is unreachable or not responding to email). A bad
reason to transfer ownership is because you don't agree with the
direction of the PEP. We try to build consensus around a PEP, but if
that's not possible, you can always submit a competing PEP.
reason to transfer ownership is because the author doesn't agree with the
direction of the PEP. One aim of the PEP process is to try to build
consensus around a PEP, but if that's not possible, an author can always
submit a competing PEP.
If you are interested in assuming ownership of a PEP, send a message
asking to take over, addressed to both the original author and the PEP
editor <peps@python.org>. If the original author doesn't respond to
email in a timely manner, the PEP editor will make a unilateral
editors <peps@python.org>. If the original author doesn't respond to
email in a timely manner, the PEP editors will make a unilateral
decision (it's not like such decisions can't be reversed :).
@ -463,7 +490,7 @@ PEP Editor Responsibilities & Workflow
======================================
A PEP editor must subscribe to the <peps@python.org> list. All
PEP-related correspondence should be sent (or CC'd) to
correspondence related to PEP administration should be sent (or forwarded) to
<peps@python.org> (but please do not cross-post!).
For each new PEP that comes in an editor does the following:
@ -478,20 +505,20 @@ For each new PEP that comes in an editor does the following:
etc.), markup (for reST PEPs), code style (examples should match PEP
8 & 7).
If the PEP isn't ready, the editor will send it back to the author for
If the PEP isn't ready, an editor will send it back to the author for
revision, with specific instructions.
Once the PEP is ready for the repository, the PEP editor will:
Once the PEP is ready for the repository, a PEP editor will:
* Assign a PEP number (almost always just the next available number,
but sometimes it's a special/joke number, like 666 or 3141).
(Clarification: For Python 3, we used numbers in the 3000s for
(Clarification: For Python 3, numbers in the 3000s were used for
Py3k-specific proposals. But now that all new features go into
Python 3 only, we're back to using numbers in the 100s again.
Python 3 only, the process is back to using numbers in the 100s again.
Remember that numbers below 100 are meta-PEPs.)
* Add the PEP to a local clone of the PEP repository. For mercurial work
flow instructions, follow `The Python Developers Guide <http://docs.python.org/devguide>`_
* Add the PEP to a local clone of the PEP repository. For mercurial workflow
instructions, follow `The Python Developers Guide <http://docs.python.org/devguide>`_
The mercurial repo for the peps is::
@ -502,9 +529,11 @@ Once the PEP is ready for the repository, the PEP editor will:
will not be updated to reflect the PEP changes.
* Commit and push the new (or updated) PEP
* Monitor python.org to make sure the PEP gets added to the site
properly.
properly. If it fails to appear, running ``make`` will build all of the
current PEPs. If any of these are triggering errors, they must be
corrected before any PEP will update on the site.
* Send email back to the PEP author with next steps (post to
python-list & -dev).
@ -515,11 +544,10 @@ authors are not Python committers yet, so PEP editors do the commits for them.
Many PEPs are written and maintained by developers with write access
to the Python codebase. The PEP editors monitor the python-checkins
list for PEP changes, and correct any structure, grammar, spelling, or
markup mistakes we see.
markup mistakes they see.
The editors don't pass judgment on PEPs. We merely do the
administrative & editorial part. Except for times like this, there's
relatively low volume.
PEP editors don't pass judgment on PEPs. They merely do the
administrative & editorial part (which is generally a low volume task).
Resources:
@ -572,7 +600,7 @@ Copyright
This document has been placed in the public domain.
..
Local Variables:
mode: indented-text

View File

@ -15,14 +15,15 @@ Created: 13-Jul-2000
"""
intro = u"""
The PEP contains the index of all Python Enhancement Proposals,
known as PEPs. PEP numbers are assigned by the PEP Editor, and
once assigned are never changed. The Mercurial history[1] of
This PEP contains the index of all Python Enhancement Proposals,
known as PEPs. PEP numbers are assigned by the PEP editors, and
once assigned are never changed[1]. The Mercurial history[2] of
the PEP texts represent their historical record.
"""
references = u"""
[1] View PEP history online
[1] PEP 1: PEP Purpose and Guidelines
[2] View PEP history online
http://hg.python.org/peps/
"""