Fleshed out the bulk of the guidelines, after internal discussion

among the PEP authors and the BDFL.

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)
+Author: bwarsaw@beopen.com (Barry A. Warsaw),
-Status: Incomplete
+    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 <bwarsaw@beopen.com>, 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 <guido@beopen.com>) 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: <pep number>
+        Title: <pep title>
+        Version: <cvs version string>
+        Author: <list of authors' email and real name>
+        Status: <Draft | Accepted | Deferred | Final>
+        Type: <Informational | Standards Track>
+        Created: <date created on, in dd-mmm-yyyy format>
+        Post-History: <dates of postings to python-list and python-dev>
+
+    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: