python
diff --git a/‎pep-0001.txt
Lines changed: 68 additions & 52 deletions b/‎pep-0001.txt
Lines changed: 68 additions & 52 deletions
@@ -92,15 +92,14 @@ details.  The current editors are:
 * Guido van Rossum
 * Barry Warsaw
 
-PEP editorship is by invitation of the current editors.  The address
-<peps@python.org> is a mailing list for contacting the 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).
+PEP editorship is by invitation of the current editors, and they can be
+contacted via the address <peps@python.org>, but you may only need to use this
+to contact the editors semi-privately.  All of the PEP workflow can be
+conducted via the GitHub `PEP repository`_ issues and pull requests.
 
 
-Submitting a PEP
-----------------
+Start with an idea for Python
+-----------------------------
 
 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
@@ -111,13 +110,13 @@ 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.
 
-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 mailing list is the best way to go about this.
+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.
 
 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
@@ -136,35 +135,46 @@ 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 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 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 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
-not in keeping with the Python philosophy.  The BDFL can be consulted
-during the approval phase, and is the final arbiter of the draft's
-PEP-ability.
-
-Developers with git push 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`_). 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
-git push privileges and they can guide you through the process of updating
-the PEP repository directly.
+
+Submitting a PEP
+----------------
+
+Following a discussion on python-ideas, the proposal should be submitted as a
+draft PEP via a `GitHub pull request`_.  The draft must be written in PEP
+style as described below, else it will fail review immediately (although minor
+errors may be corrected by the editors).
+
+The standard PEP workflow is:
+
+* You, the PEP author, fork the `PEP repository`_, and create a file named
+  ``pep-0xxx.rst`` that contains your new PEP.  Use "XXX" as your draft PEP
+  number.
+* Push this to your GitHub fork and submit a pull request.
+* The PEP editors review your PR for structure, formatting, and other errors.
+* Once approved, they will assign your PEP a number, and label it as Standards
+  Track, Informational, or Process, and give it the status "Draft"
+
+Once the review process is complete, and the PEP editors approve it (note that
+this is *not* the same as accepting your PEP!), they will squash commit your
+pull request onto master.
+
+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 not in keeping
+with the Python philosophy.  The BDFL can be consulted during the approval
+phase, and is the final arbiter of the draft's PEP-ability.
+
+Developers with git push 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`_). This includes
+ensuring the initial version meets the expected standards for submitting a
+PEP. Alternately, even developers may choose to submit PEPs via pull request.
+When doing so, let the PEP editors know you have git 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
-(or a collaborating developer) have git push privileges, or else they can
-email new PEP versions to the PEP editors for publication.
+(or a collaborating developer) have git push privileges.
 
 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
@@ -491,19 +501,22 @@ 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
-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 :).
+If you are interested in assuming ownership of a PEP, you can also do this via
+pull request.  Fork the `PEP repository`_, make your ownership modification,
+and submit a pull request.  You should also send a message asking to take
+over, addressed to both the original author and the PEP 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 :).
 
 
 PEP Editor Responsibilities & Workflow
 ======================================
 
-A PEP editor must subscribe to the <peps@python.org> list.  All
-correspondence related to PEP administration should be sent (or forwarded) to
-<peps@python.org> (but please do not cross-post!).
+A PEP editor must subscribe to the <peps@python.org> list and must watch the
+`PEP repository`_.  Most correspondence regarding PEP administration can be
+handled through GitHub issues and pull requests, but you may also use
+<peps@python.org> for semi-private discussions.  Please do not cross-post!
 
 For each new PEP that comes in an editor does the following:
 
@@ -529,7 +542,7 @@ Once the PEP is ready for the repository, a PEP editor will:
   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 workflow
+* Add the PEP to a local fork of the PEP repository.  For workflow
   instructions, follow `The Python Developers Guide <http://docs.python.org/devguide>`_
 
   The git repo for the peps is::
@@ -550,8 +563,8 @@ Once the PEP is ready for the repository, a PEP editor will:
 * Send email back to the PEP author with next steps (post to
 
-Updates to existing PEPs also come in to peps@python.org.  Many PEP
-authors are not Python committers yet, so PEP editors do the commits for them.
+Updates to existing PEPs should be submitted as a `GitHub pull request`_.
+Questions may of course still be sent to <peps@python.org>.
 
 Many PEPs are written and maintained by developers with write access
 to the Python codebase.  The PEP editors monitor the python-checkins
@@ -573,6 +586,7 @@ Resources:
 * `Frequently Asked Questions for Developers
   <http://docs.python.org/devguide/faq.html>`_
 
+
 References and Footnotes
 ========================
 
@@ -606,6 +620,8 @@ References and Footnotes
 
 .. _PEP repository: https://github.com/python/peps
 
+.. _`GitHub pull request`: https://github.com/python/peps/pulls
+
 
 Copyright
 =========