From 4942fa6425bf26d6fc34acf397171ad02863ee74 Mon Sep 17 00:00:00 2001 From: Jarrod Millman Date: Mon, 11 Dec 2017 11:47:07 -0800 Subject: [PATCH] DOC: Copy PEP 1 This is an exact copy of PEP1 to make it easier to see how I changed it: https://github.com/python/peps/blob/master/pep-0001.txt --- doc/neps/nep-0000.rst | 636 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 636 insertions(+) create mode 100644 doc/neps/nep-0000.rst diff --git a/doc/neps/nep-0000.rst b/doc/neps/nep-0000.rst new file mode 100644 index 000000000000..8232af4c293a --- /dev/null +++ b/doc/neps/nep-0000.rst @@ -0,0 +1,636 @@ +PEP: 1 +Title: PEP Purpose and Guidelines +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, 05-May-2012, + 07-Apr-2013 + + +What is a PEP? +============== + +PEP stands for Python Enhancement Proposal. A PEP is a design +document providing information to the Python community, or describing +a new feature for Python or its processes or environment. The PEP +should provide a concise technical specification of the feature and a +rationale for the feature. + +We intend PEPs to be the primary mechanisms for proposing major new +features, for collecting community input on an issue, and for +documenting the design decisions that have gone into Python. The PEP +author is responsible for building consensus within the community and +documenting dissenting opinions. + +Because the PEPs are maintained as text files in a versioned +repository, their revision history is the historical record of the +feature proposal [1]_. + + +PEP Types +========= + +There are three kinds of PEP: + +1. A **Standards Track** PEP describes a new feature or implementation + for Python. It may also describe an interoperability standard that will + be supported outside the standard library for current Python versions + before a subsequent PEP adds standard library support in a future + version. + +2. An **Informational** PEP describes a Python design issue, or + provides general guidelines or information to the Python community, + but does not propose a new feature. Informational PEPs do not + necessarily represent a Python community consensus or + recommendation, so users and implementers are free to ignore + Informational PEPs or follow their advice. + +3. A **Process** PEP describes a process surrounding Python, or + proposes a change to (or an event in) a process. Process PEPs are + like Standards Track PEPs but apply to areas other than the Python + language itself. They may propose an implementation, but not to + Python's codebase; they often require community consensus; unlike + Informational PEPs, they are more than recommendations, and users + are typically not free to ignore them. Examples include + procedures, guidelines, changes to the decision-making process, and + changes to the tools or environment used in Python development. + Any meta-PEP is also considered a Process PEP. + + +PEP Workflow +============ + + +Python's BDFL +------------- + +There are several references in this PEP to the "BDFL". This acronym stands +for "Benevolent Dictator for Life" and refers to Guido van Rossum, the +original creator of, and the final design authority for, the Python +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: + +* Chris Angelico +* Anthony Baxter +* Georg Brandl +* Brett Cannon +* David Goodger +* R. David Murray +* Jesse Noller +* Berker Peksag +* Guido van Rossum +* Barry Warsaw + +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. + + +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 +idea. Small enhancements or patches often don't need +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 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@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 +forward for changing Python that have been rejected for various +reasons. Asking the Python community first if an idea is original +helps prevent too much time being spent on something that is +guaranteed to be rejected based on prior discussions (searching +the internet does not always do the trick). It also helps to make sure +the idea is applicable to the entire community and not just the author. +Just because an idea sounds good to the author does not +mean it will work for most people in most areas where Python is used. + +Once the champion has asked the Python community as to whether an +idea has any chance of acceptance, a draft PEP should be presented to +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). + +The standard PEP workflow is: + +* You, the PEP author, fork the `PEP repository`_, and create a file named + ``pep-9999.rst`` that contains your new PEP. Use "9999" 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. + +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 `__ for review as described +in the next section. + +Standards Track PEPs consist of two parts, a design document and a +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 +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 may request a review for +style and consistency from the PEP editors. However, the content and +final acceptance of the PEP must be requested of the BDFL, usually via +an email to the python-dev mailing list. PEPs are reviewed by the +BDFL and his chosen consultants, who may accept or reject a PEP or +send it back to the author(s) for revision. For a PEP that is +predetermined to be acceptable (e.g., it is an obvious win as-is +and/or its implementation 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 BDFL's delegate (or "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. + +If the final decision on a PEP is to be made by a delegate rather than +directly by the BDFL, this will be recorded by including the +"BDFL-Delegate" header in the PEP. + +PEP review and resolution may also occur on a list other than python-dev +(for example, distutils-sig for packaging related PEPs that don't +immediately affect the standard library). In this case, the "Discussions-To" +heading in the PEP will identify the appropriate alternative list where +discussion, review and pronouncement on the PEP will occur. + +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 +implementation, if applicable, must be solid and must not complicate +the interpreter unduly. Finally, a proposed enhancement must be +"pythonic" in order to be accepted by the BDFL. (However, "pythonic" +is an imprecise term; it may be defined as whatever is acceptable to +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 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 an +editor can assign the PEP this status when no progress is being made +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 +was not a good idea. It is still important to have a record of this +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 +an API can replace version 1. + +The possible paths of the status of PEPs are as follows: + +.. image:: pep-0001-1.png + +Some Informational and Process PEPs may also have a status of "Active" +if they are never meant to be completed. E.g. PEP 1 (this PEP). + + +PEP Maintenance +--------------- + +In general, Standards track PEPs are no longer modified after they have +reached the Final state. Once a PEP has been completed, the Language and +Standard Library References become the formal documentation of the expected +behavior. + +Informational and Process PEPs may be updated over time to reflect changes +to development practices and other details. The precise process followed in +these cases will depend on the nature and purpose of the PEP being updated. + + + +What belongs in a successful PEP? +================================= + +Each PEP should have the following parts: + +1. Preamble -- RFC 822 style headers containing meta-data about the + PEP, including the PEP number, a short descriptive title (limited + to a maximum of 44 characters), the names, and optionally the + contact info for each author, etc. + +2. Abstract -- a short (~200 word) description of the technical issue + being addressed. + +3. Copyright/public domain -- Each PEP must either be explicitly + labeled as placed in the public domain (see this PEP as an + example) or licensed under the `Open Publication License`_. + +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 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 + existing language specification is inadequate to address the + problem that the PEP solves. PEP submissions without sufficient + motivation may be rejected outright. + +6. Rationale -- The rationale fleshes out the specification by + describing what motivated the design and why particular design + decisions were made. It should describe alternate designs that + were considered and related work, e.g. how the feature is supported + in other languages. + + The rationale should provide evidence of consensus within the + community and discuss important objections or concerns raised + during discussion. + +7. Backwards Compatibility -- All PEPs that introduce backwards + incompatibilities must include a section describing these + incompatibilities and their severity. The PEP must explain how the + author proposes to deal with these incompatibilities. PEP + submissions without a sufficient backwards compatibility treatise + may be rejected outright. + +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. 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 + standard library reference. + + +PEP Formats and Templates +========================= + +PEPs are UTF-8 encoded text files using the reStructuredText_ format. +ReStructuredText_ allows for rich markup that is still quite easy to +read, but also results in good-looking and functional HTML. PEP 12 +contains instructions and a template [4]_ for reStructuredText PEPs. + +A Python script automatically converts PEPs to HTML for viewing on +the web [5]_. The conversion of reStructuredText PEPs is handled by +the Docutils_ module; the same script also renders a legacy plain-text +format of PEP internally, to support pre-reST documents. + + +PEP Header Preamble +=================== + +Each PEP must begin with an RFC 822 style header preamble. The headers +must appear in the following order. Headers marked with "*" are +optional and are described below. All other headers are required. :: + + PEP: + Title: + Author: + * BDFL-Delegate: + * Discussions-To: + Status: + Type: + * Content-Type: + * Requires: + Created: + * Python-Version: + Post-History: + * Replaces: + * Superseded-By: + * Resolution: + +The Author header lists the names, and optionally the email addresses +of all the authors/owners of the PEP. The format of the Author header +value must be + + Random J. User + +if the email address is included, and just + + Random J. User + +if the address is not given. For historical reasons the format +"address@dom.ain (Random J. User)" may appear in a PEP, however new +PEPs must use the mandated format above, and it is acceptable to +change to this format when PEPs are updated. + +If there are multiple authors, each should be on a separate line +following RFC 2822 continuation line conventions. Note that personal +email addresses in PEPs will be obscured as a defense against spam +harvesters. + +The BDFL-Delegate field is used to record cases where the final decision to +approve or reject a PEP rests with someone other than the BDFL. (The +delegate's email address is currently omitted due to a limitation in the +email address masking for reStructuredText PEPs) + +*Note: The Resolution header is required for Standards Track PEPs +only. It contains a URL that should point to an email message or +other web resource where the pronouncement about the PEP is made.* + +For a PEP where final pronouncement will be made on a list other than +python-dev, a Discussions-To header will indicate the mailing list +or URL where the pronouncement will occur. A temporary Discussions-To header +may also be used when a draft PEP is being discussed prior to submission for +pronouncement. No Discussions-To header is necessary if the PEP is being +discussed privately with the author, or on the python-list, python-ideas +or python-dev mailing lists. Note that email addresses in the +Discussions-To header will not be obscured. + +The Type header specifies the type of PEP: Standards Track, +Informational, or Process. + +The format of a PEP is specified with a Content-Type header. The +acceptable values are "text/plain" for plaintext PEPs (see PEP 9 [3]_) +and "text/x-rst" for reStructuredText PEPs (see PEP 12 [4]_). +reStructuredText is strongly preferred, but for backwards +compatibility plain text is currently still the default if no +Content-Type header is present. + +The Created header records the date that the PEP was assigned a +number, while Post-History is used to record the dates of when new +versions of the PEP are posted to python-ideas and/or python-dev. Both +headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. + +Standards Track PEPs will typically have a Python-Version header which +indicates the version of Python that the feature will be released with. +Standards Track PEPs without a Python-Version header indicate +interoperability standards that will initially be supported through +external libraries and tools, and then supplemented by a later PEP to +add support to the standard library. Informational and Process PEPs do +not need a Python-Version header. + +PEPs may have a Requires header, indicating the PEP numbers that this +PEP depends on. + +PEPs may also have a Superseded-By header indicating that a PEP has +been rendered obsolete by a later document; the value is the number of +the PEP that replaces the current document. The newer PEP must have a +Replaces header containing the number of the PEP that it rendered +obsolete. + + +Auxiliary Files +=============== + +PEPs may include auxiliary files such as diagrams. Such files must be +named ``pep-XXXX-Y.ext``, where "XXXX" is the PEP number, "Y" is a +serial number (starting at 1), and "ext" is replaced by the actual +file extension (e.g. "png"). + + +Reporting PEP Bugs, or Submitting PEP Updates +============================================= + +How you report a bug, or submit a PEP update depends on several +factors, such as the maturity of the PEP, the preferences of the PEP +author, and the nature of your comments. For the early draft stages +of the PEP, it's probably best to send your comments and changes +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 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 a PEP editor. + +PEP authors with git push privileges for the PEP repository can update the +PEPs themselves by using "git push" to submit their changes. + + +Transferring PEP Ownership +========================== + +It occasionally becomes necessary to transfer ownership of PEPs to a +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 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, 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 +. 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 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: + +* Read the PEP to check if it is ready: sound and complete. The ideas + must make technical sense, even if they don't seem likely to be + accepted. + +* The title should accurately describe the content. + +* Edit the PEP for language (spelling, grammar, sentence structure, + etc.), markup (for reST PEPs), code style (examples should match PEP + 8 & 7). + +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, 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, numbers in the 3000s were used for + Py3k-specific proposals. But now that all new features go into + 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 fork of the PEP repository. For workflow + instructions, follow `The Python Developers Guide `_ + + The git repo for the peps is:: + + https://github.com/python/peps + +* Run ``./genpepindex.py`` and ``./pep2html.py `` 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. 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). + +Updates to existing PEPs should be submitted as a `GitHub pull request`_. +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 +list for PEP changes, and correct any structure, grammar, spelling, or +markup mistakes they see. + +PEP editors don't pass judgment on PEPs. They merely do the +administrative & editorial part (which is generally a low volume task). + +Resources: + +* `Index of Python Enhancement Proposals `_ + +* `Following Python's Development + `_ + +* `Python Developer's Guide `_ + +* `Frequently Asked Questions for Developers + `_ + + +References and Footnotes +======================== + +.. [1] This historical record is available by the normal git commands + for retrieving older revisions, and can also be browsed via HTTP here: + https://github.com/python/peps + +.. [2] PEP 2, Procedure for Adding New Modules, Faassen + (http://www.python.org/dev/peps/pep-0002) + +.. [3] PEP 9, Sample Plaintext PEP Template, Warsaw + (http://www.python.org/dev/peps/pep-0009) + +.. [4] PEP 12, Sample reStructuredText PEP Template, Goodger, Warsaw + (http://www.python.org/dev/peps/pep-0012) + +.. [5] The script referred to here is pep2pyramid.py, the successor to + pep2html.py, both of which live in the same directory in the hg + repo as the PEPs themselves. Try ``pep2html.py --help`` for + details. The URL for viewing PEPs on the web is + http://www.python.org/dev/peps/. + +.. _issue tracker: + http://bugs.python.org/ + +.. _Open Publication License: http://www.opencontent.org/openpub/ + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html + +.. _Docutils: http://docutils.sourceforge.net/ + +.. _PEP repository: https://github.com/python/peps + +.. _`GitHub pull request`: https://github.com/python/peps/pulls + + +Copyright +========= + +This document has been placed in the public domain. + + +.. + Local Variables: + mode: indented-text + indent-tabs-mode: nil + sentence-end-double-space: t + fill-column: 70 + coding: utf-8 + End: