Skip to content

Commit

Permalink
Closes python#38 (python#116)
Browse files Browse the repository at this point in the history 
* Closes python#38

* Updated workflow.

* Respond to review.

* s/clone/fork/

Use GitHub terminology rather than generic git terminology.
  • Loading branch information
@warsaw @ncoghlan
warsaw authored and ncoghlan committed Oct 15, 2016
1 parent 6efb70f commit 1cdddf8
Showing 1 changed file with 68 additions and 52 deletions.
120 changes: 68 additions & 52 deletions pep-0001.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
<[email protected]> 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 <[email protected]>, 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
Expand All @@ -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. [email protected] 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. [email protected] mailing list) or the [email protected]
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
Expand All @@ -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 <[email protected]>. 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
Expand Down Expand Up @@ -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 <[email protected]>. 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
<[email protected]>. 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 <[email protected]> list. All
correspondence related to PEP administration should be sent (or forwarded) to
<[email protected]> (but please do not cross-post!).
A PEP editor must subscribe to the <[email protected]> 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
<[email protected]> for semi-private discussions. Please do not cross-post!

For each new PEP that comes in an editor does the following:

Expand All @@ -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::
Expand All @@ -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
python-list & -dev).

Updates to existing PEPs also come in to [email protected]. 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 <[email protected]>.

Many PEPs are written and maintained by developers with write access
to the Python codebase. The PEP editors monitor the python-checkins
Expand All @@ -573,6 +586,7 @@ Resources:
* `Frequently Asked Questions for Developers
<http://docs.python.org/devguide/faq.html>`_


References and Footnotes
========================

Expand Down Expand Up @@ -606,6 +620,8 @@ References and Footnotes

.. _PEP repository: https://github.com/python/peps

.. _`GitHub pull request`: https://github.com/python/peps/pulls


Copyright
=========
Expand Down

0 comments on commit 1cdddf8

Please sign in to comment.