PEP: 1 Title: PEP Purpose and Guidelines Version: $Revision$ Author: barry@digicool.com (Barry A. Warsaw), jeremy@digicool.com (Jeremy Hylton) Status: Draft Type: Informational Created: 13-Jun-2000 Post-History: 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. 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 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 plain text files under CVS control, their revision history is the historical record of the feature proposal[1]. Kinds of PEPs There are two kinds of PEPs. A standards track PEP describes a new feature or implementation for Python. 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. PEP Workflow The PEP editor, Barry Warsaw , assigns numbers for each PEP and changes its status. When a new feature is introduced on python-dev, a brief high-level discussion should be conducted, not on the merits of the proposal, but on whether the idea is significant enough to warrant a PEP. Should consensus on PEP-ability be reached, a champion must be identified. The champion offers to take the discussion off-line and specifies a location (e.g. egroups, python.org, Roundup). The champion then emails the PEP editor with a proposed title and a rough, but fleshed out, draft of the PEP. If the PEP editor approves, he will assign the PEP a number, label it as standards track or informational, give it status 'draft', and create and check-in the initial draft of the PEP. The PEP editor will not unreasonably deny a PEP. Reasons for denying PEP status include duplication of effort, being technically unsound, or not in keeping with the Python philosophy; the BDFL (Benevolent Dictator for Life, Guido van Rossum ) is the final arbitrator of the latter. In general, an initial draft of the PEP should be prepared before discussion occurs on the python-dev and pyton-list mailing lists. The author should incorporate comments and feedback into this initial draft when possible. The authors of the PEP are then responsible for writing the PEP and marshaling community support for it. The structure of a PEP is described in detail below. The PEP consists of two parts, a design document and a reference implementation. The PEP should be reviewed and accepted before a reference implementation is begun, unless a reference implementation will aid people in studying the PEP. A Standards Track PEP must include an implementation - in the form of code, patch, or URL to same - before it can be considered Final. PEP authors are responsible for collecting community feedback on a PEP before submitting it for review. A PEP that has not been discussed on python-list and python-dev will not be accepted for review. However, wherever possible, long open-ended discussions on public mailing lists should be avoided. A better strategy is to encourage public feedback directly to the PEP author, who collects and integrates the comments back into the PEP. 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 the author(s) for revision. Once a PEP has been accepted, the reference implementation must be completed. When the reference implementation is complete and accepted by the BDFL, 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 on the PEP. Once a PEP is deferred, the 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. PEP work flow is as follows: Draft -> Accepted -> Final ^ +----> Rejected v Deferred Some informational PEPs may also have a status of `Active' if they are never meant to be completed. E.g. PEP 1. What belongs in a successful PEP? Each PEP should have the following parts: 1. Title -- a short, descriptive title 2. Author(s) -- names and contact info for each author 3. Abstract -- a short (~200 word) description of the technical issue being addressed 4. Copyright/public domain -- Each PEP must either be explicitly labelled in the public domain or the Open Publication License[2]. 5. 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 any of the current Python platforms (CPython, JPython, Python .NET). 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. 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. It is better to finish the specification and rationale first and reach consensus on it before writing code. The final implementation must include test code and documentation appropriate for either the Python language reference or the standard library reference. PEP Style PEPs are written in plain ASCII text, and should adhere to a rigid style. There is a Python script that parses this style and converts the plain text PEP to HTML for viewing on the web[3]. Each PEP begins with an RFC822 style header section. Required headers are as follows, and must appear in this order: PEP: Title: Version: Author: Status: Type: Created: Post-History: Standards track PEPs should additionally have a Python-Version: header which indicates the version of Python that the feature will be released with. While a PEP is in private discussions (usually during the initial Draft phase), a Discussions-To: header will indicate the mailing list or URL where the PEP is being discussed. PEP headings should begin in column zero and should be capitalized. The body of each section should be indented 4 spaces. Code samples inside body sections should be indented a further 4 spaces, and other indentation can be used as required to make the text readable. You should use two blank lines between the last line of a section's body and the next section heading. No tabs should appear in the document at all. A PEP should include the Emacs stanza included by example in this PEP to aid Emacs editors. A PEP must contain a Copyright heading, and it is strongly recommended to put the PEP in the public domain. You should footnote any URLs in the body of the PEP, and a PEP should include a References section with those URLs expanded. Copyright This document has been placed in the public domain. References and Footnotes [1] This historical record is available by the normal CVS commands for retrieving older revisions. For those without direct access to the CVS tree, you can browse the current and past PEP revisions via the SourceForge web site at http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/python/nondist/peps/?cvsroot=python [2] http://www.opencontent.org/openpub/ [3] The script referred to here is pep2html.py, which lives in the same directory in the CVS tree as the PEPs themselves. Try "pep2html.py --help" for details. The URL for viewing PEPs on the web is http://python.sourceforge.net/peps/ Local Variables: mode: indented-text indent-tabs-mode: nil End: