Update PEP 1 to better reflect current practice

pep-0001.txt

@@ -2,12 +2,12 @@ PEP: 1
 Title: PEP Purpose and Guidelines
 Version: $Revision$
 Last-Modified: $Date$
-Author: Barry Warsaw, Jeremy Hylton, David Goodger
+Author: Barry Warsaw, Jeremy Hylton, David Goodger, Nick Coghlan
 Status: Active
 Type: Process
 Content-Type: text/x-rst
 Created: 13-Jun-2000
-Post-History: 21-Mar-2001, 29-Jul-2002, 03-May-2003
+Post-History: 21-Mar-2001, 29-Jul-2002, 03-May-2003, 05-May-2012
 
 
 What is a PEP?
@@ -60,6 +60,9 @@ There are three kinds of PEP:
 PEP Work Flow
 =============
 
+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.
@@ -115,6 +118,11 @@ not in keeping with the Python philosophy.  The BDFL (Benevolent
 Dictator for Life, Guido van Rossum) can be consulted during the
 approval phase, and is the final arbiter of the draft's PEP-ability.
 
+Developers with commit privileges for the `PEP repository`_ may claim
+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 PEP editors (see `PEP Editor Responsibilities & Workflow`_).
+
 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 editor for committing.
@@ -134,6 +142,9 @@ 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.
 
+PEP Review & Resolution
+-----------------------
+
 Once the authors have completed a PEP, they must inform the PEP editor
 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
@@ -143,6 +154,16 @@ has already been checked in) the BDFL may also initiate a PEP review,
 first notifying the PEP author(s) and giving them a chance to make
 revisions.
 
+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
+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
+other core developers and the BDFL, then they will have the authority to
+approve (or reject) that PEP. This process happens most frequently with PEPs
+where the BDFL has granted in principle approval for *something* to be done,
+but there are details that need to be worked out before the PEP can be
+accepted.
+
 For a PEP to be accepted it must meet certain minimum criteria.  It
 must be a clear and complete description of the proposed enhancement.
 The enhancement must represent a net improvement.  The proposed
@@ -154,8 +175,8 @@ the BDFL.  This logic is intentionally circular.)  See PEP 2 [2]_ for
 standard library module acceptance criteria.
 
 Once a PEP has been accepted, the reference implementation must be
-completed.  When the reference implementation is complete and accepted
+completed.  When the reference implementation is complete and incorporated
-by the BDFL, the status will be changed to "Final".
+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
 editor can assign the PEP this status when no progress is being made
@@ -164,7 +185,14 @@ to draft status.
 
 A PEP can also be "Rejected".  Perhaps after all is said and done it
 was not a good idea.  It is still important to have a record of this
-fact.
+fact. The "Withdrawn" status is similar - it means that the PEP author
+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
+the Resolution header should be added with a link to the relevant post
+in the python-dev mailing list archives.
 
 PEPs can also be superseded by a different PEP, rendering the original
 obsolete.  This is intended for Informational PEPs, where version 2 of
@@ -420,16 +448,18 @@ Once the PEP is ready for the repository, the PEP editor will:
   Python 3 only, we're back to using numbers in the 100s again.
   Remember that numbers below 100 are meta-PEPs.)
 
-* List the PEP in PEP 0 (in two places: the categorized list, and the
+* Add the PEP to a local clone of the PEP repository.  For mercurial work
-  numeric list).
+  flow instructions, follow `The Python Developers Guide <http://docs.python.org/devguide>`_
-
-* Add the PEP to Mercurial.  For mercurial work flow instructions, follow
-  `The Python Developers Guide <http://docs.python.org/devguide>`_
 
   The mercurial repo for the peps is::
 
     http://hg.python.org/peps/
 
+* Run ``./genpepindex.py`` and ``./pep2html.py <PEP Number>`` to ensure they
+  are generated without errors. If either triggers errors, then the web site
+  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.
@@ -438,7 +468,7 @@ Once the PEP is ready for the repository, the PEP editor will:
   python-list & -dev).
 
 Updates to existing PEPs also come in to peps@python.org.  Many PEP
-authors are not Python committers yet, so we do the commits for them.
+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
@@ -492,6 +522,8 @@ References and Footnotes
 
 .. _Docutils: http://docutils.sourceforge.net/
 
+.. _PEP repository: http://hg.python.org/peps
+
 
 Copyright
 =========