peps: be7150dbe20c (original) (raw)

--- a/pep-0001.txt +++ b/pep-0001.txt @@ -1,8 +1,208 @@ PEP: 1 -Title: PEP Guidelines +Title: PEP Purpose and Guidelines Version: RevisionRevisionRevision -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 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[](#l1.110)

```
     ^[](#l1.111)
```
```
     +----> Rejected[](#l1.112)
```
```
     v[](#l1.113)
```
```
   Deferred[](#l1.114)
```

+ + +What belongs in a successful PEP? +

Each PEP should have the following parts:

1. Title -- a short, descriptive title

1. Author(s) -- names and contact info for each author

1. Abstract -- a short (~200 word) description of the technical issue
```
  being addressed[](#l1.126)
```

1. Copyright/public domain -- Each PEP must either be explicitly

  labelled in the public domain or the Open Publication[](#l1.129)

```
  License[1].[](#l1.130)
```

1. Specification -- The technical specification should describe

  the syntax and semantics of any new language feature.  The[](#l1.133)

  specification should be detailed enough to allow competing,[](#l1.134)

  interoperable implementations for any of the current Python[](#l1.135)

  platforms (CPython, JPython, Python .NET).[](#l1.136)

1. Rationale -- The rationale fleshes out the specification by

  describing what motivated the design and why particular design[](#l1.139)

  decisions were made.  It should describe alternate designs that[](#l1.140)

  were considered and related work, e.g. how the feature is[](#l1.141)

  supported in other languages.[](#l1.142)

  The rationale should provide evidence of consensus within the[](#l1.144)

  community and discuss important objections or concerns raised[](#l1.145)

```
  during discussion.[](#l1.146)
```

1. Reference Implementation -- The reference implementation must

  be completed before any PEP is given status 'final,' but it[](#l1.149)

  need not be completed before the PEP is accepted.  It is better[](#l1.150)

  to finish the specification and rationale first and reach[](#l1.151)

  consensus on it before writing code.[](#l1.152)

  The final implementation must include test code and[](#l1.154)

  documentation appropriate for either the Python language[](#l1.155)

  reference or the standard library reference.[](#l1.156)

+ + +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>[](#l1.168)
```
```
   Title: <pep title>[](#l1.169)
```

   Version: <cvs version string>[](#l1.170)

   Author: <list of authors' email and real name>[](#l1.171)

   Status: <Draft | Accepted | Deferred | Final>[](#l1.172)

   Type: <Informational | Standards Track>[](#l1.173)

   Created: <date created on, in dd-mmm-yyyy format>[](#l1.174)

   Post-History: <dates of postings to python-list and python-dev>[](#l1.175)

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/[](#l1.210)

+ Local Variables: