diff --git a/pep-0001.txt b/pep-0001.txt index 30698590b..08214519a 100644 --- a/pep-0001.txt +++ b/pep-0001.txt @@ -1,8 +1,208 @@ PEP: 1 -Title: PEP Guidelines +Title: PEP Purpose and Guidelines Version: $Revision$ -Owner: bwarsaw@beopen.com (Barry A. Warsaw) -Status: Incomplete +Author: bwarsaw@beopen.com (Barry A. Warsaw), + jeremy@beopen.com (Jeremy Hylton) +Status: Draft +Type: Informational +Created: 13-Jun-2000 +Post-History: + + +What is a PEP? + + PEP standards 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. + + +Kinds of PEPs + + There are two kinds of PEPs. A standards track PEP describes a + new feature 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 describing the proposal + and its title. 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 an initial template for + 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. + + Discussion concerning a PEP should initially be kept out of the + python-dev and python-list mailing lists. Instead, comments + should be sent to, and collected by, the PEP owner, who has the + responsibility to incorporate these comments into the document. + + 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 + + +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[1]. + + 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. + + 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 heading 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 + + [1] http://www.opencontent.org/openpub/ + Local Variables: