From 352ac9e6b300b99706dd959e3082ae8fa229030f Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 13 Oct 2016 16:51:34 -0400 Subject: [PATCH 1/4] Closes #38 --- pep-0001.txt | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 784c6a8496e..89b913662d7 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -98,6 +98,9 @@ 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). +The PEP editors watch the GitHub `PEP repository`_, so that's also a good way +to get in contact with them. + Submitting a PEP ---------------- @@ -136,11 +139,10 @@ 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 . 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). +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). If the PEP editors approve, they will assign the PEP a number, label it as Standards Track, Informational, or Process, give it status "Draft", @@ -549,8 +551,9 @@ 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 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 PEP 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 @@ -605,6 +608,8 @@ References and Footnotes .. _PEP repository: https://github.com/python/peps +.. _`GitHub pull request`: https://github.com/python/peps/pulls + Copyright ========= From aa71e3eb64ac74c5c82449ffdf8f508bf1576187 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 13 Oct 2016 17:20:19 -0400 Subject: [PATCH 2/4] Updated workflow. --- pep-0001.txt | 106 ++++++++++++++++++++++++++++----------------------- 1 file changed, 59 insertions(+), 47 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 89b913662d7..02f446936e8 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -92,18 +92,14 @@ details. The current editors are: * Guido van Rossum * Barry Warsaw -PEP editorship is by invitation of the current editors. The address - 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 , 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. -The PEP editors watch the GitHub `PEP repository`_, so that's also a good way -to get in contact with them. - -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 @@ -114,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 @@ -139,34 +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. + +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). -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. +The standard PEP workflow is: + +* You, the PEP author, clones the `PEP repository`_, and create a file named + `pep-xxxx.rst` that contains your new PEP. Use "XXX" as your draft PEP + number. +* Push this to your GitHub clone 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 @@ -492,19 +500,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 . 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. Clone the git 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 . +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 list. All -correspondence related to PEP administration should be sent (or forwarded) to - (but please do not cross-post!). +A PEP editor must subscribe to the 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 + for semi-private discussions. Please do not cross-post! For each new PEP that comes in an editor does the following: @@ -552,7 +563,7 @@ Once the PEP is ready for the repository, a PEP editor will: python-list & -dev). Updates to existing PEPs should be submitted as a `GitHub pull request`_. -Questions may of course still be sent to peps@python.org. Many PEP authors +Questions may of course still be sent to . Many PEP 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 @@ -575,6 +586,7 @@ Resources: * `Frequently Asked Questions for Developers `_ + References and Footnotes ======================== From 23fe9d7e24e518f8997059fd48a86b296ff3d667 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 13 Oct 2016 19:34:28 -0400 Subject: [PATCH 3/4] Respond to review. --- pep-0001.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 02f446936e8..50ba9d48c04 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -147,7 +147,7 @@ errors may be corrected by the editors). The standard PEP workflow is: * You, the PEP author, clones the `PEP repository`_, and create a file named - `pep-xxxx.rst` that contains your new PEP. Use "XXX" as your draft PEP + ``pep-0xxx.rst`` that contains your new PEP. Use "XXX" as your draft PEP number. * Push this to your GitHub clone and submit a pull request. * The PEP editors review your PR for structure, formatting, and other errors. @@ -563,8 +563,7 @@ Once the PEP is ready for the repository, a PEP editor will: python-list & -dev). Updates to existing PEPs should be submitted as a `GitHub pull request`_. -Questions may of course still be sent to . Many PEP authors -are not Python committers yet, so PEP editors do the commits for them. +Questions may of course still be sent to . Many PEPs are written and maintained by developers with write access to the Python codebase. The PEP editors monitor the python-checkins From 92ee2d007e7e3098b4018f1ecbca479dce1a1af8 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Fri, 14 Oct 2016 09:38:09 -0400 Subject: [PATCH 4/4] s/clone/fork/ Use GitHub terminology rather than generic git terminology. --- pep-0001.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pep-0001.txt b/pep-0001.txt index 3424abd4696..3f54e016b00 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -146,10 +146,10 @@ errors may be corrected by the editors). The standard PEP workflow is: -* You, the PEP author, clones the `PEP repository`_, and create a file named +* 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 clone and submit a pull request. +* 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" @@ -502,12 +502,12 @@ 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, you can also do this via -pull request. Clone the git 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 . -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 :). +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 +. 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 @@ -542,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 `_ The git repo for the peps is::