python-peps/pep-0001.txt

PEP: 1
Title: PEP Purpose and Guidelines
Version: $Revision$
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 three 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.  A technical
    PEP describes a new implementation or other internal modification
    that doesn't directly expose new features to the Python
    programmer.


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 with a proposed title and
    an abstract of about a paragraph in length.

    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

    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[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[2].

    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 | Active | 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 and Footnotes

    [1] http://www.opencontent.org/openpub/

    [2] 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.



Local Variables:
mode: indented-text
indent-tabs-mode: nil
End: