[Python-checkins] peps: Further updates to PEP 1 to better reflect current practice
nick.coghlan
python-checkins at python.org
Sat Dec 22 12:30:25 CET 2012
http://hg.python.org/peps/rev/24d5623ab21e
changeset: 4632:24d5623ab21e
user: Nick Coghlan <ncoghlan at gmail.com>
date: Sat Dec 22 21:30:14 2012 +1000
summary:
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)
files:
pep-0001.txt | 138 ++++++++++++++++++++-------------
pep0/constants.py | 9 +-
2 files changed, 88 insertions(+), 59 deletions(-)
diff --git a/pep-0001.txt b/pep-0001.txt
--- a/pep-0001.txt
+++ b/pep-0001.txt
@@ -57,8 +57,8 @@
Any meta-PEP is also considered a Process PEP.
-PEP Work Flow
-=============
+PEP Workflow
+============
Python's BDFL
@@ -70,19 +70,38 @@
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 at 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 at 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 @@
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 at python.org>`__ with the draft
-PEP and the PEP editors <peps at 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 at 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 @@
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 at 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 @@
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 @@
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 @@
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 @@
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 @@
==========================
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 at python.org>. If the original author doesn't respond to
-email in a timely manner, the PEP editor will make a unilateral
+editors <peps at 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 @@
======================================
A PEP editor must subscribe to the <peps at 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 at python.org> (but please do not cross-post!).
For each new PEP that comes in an editor does the following:
@@ -478,20 +505,20 @@
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 @@
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 @@
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 @@
This document has been placed in the public domain.
-
+
..
Local Variables:
mode: indented-text
diff --git a/pep0/constants.py b/pep0/constants.py
--- a/pep0/constants.py
+++ b/pep0/constants.py
@@ -15,14 +15,15 @@
"""
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/
"""
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list