iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Some updates based on feedback from PEP authors. Also, this applies 

SF patch #410223 by Andrew Kuchling, describing the new Replaces: and
Replaced-by: headers.
This commit is contained in:
Barry Warsaw 2001-03-21 17:05:27 +00:00
parent c3157b3336
commit 7ce8ba5d99
1 changed files with 92 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

157
pep-0001.txt
View File

@ -6,7 +6,7 @@ Author: barry@digicool.com (Barry A. Warsaw),
Status: Draft
Type: Informational
Created: 13-Jun-2000
Post-History:
Post-History: 21-Mar-2001
What is a PEP?
@ -37,52 +37,57 @@ Kinds of PEPs
feature.
PEP Workflow
PEP Work Flow
The PEP editor, Barry Warsaw <barry@digicool.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 PEP process begins with a new idea for Python. Each PEP must
have a champion -- someone who writes the PEP using the style and
format described below, shepherds the discussions in the
appropriate forums, and attempts to build community consensus
around the idea. The PEP champion (a.k.a. Author) should first
attempt to ascertain whether the idea is PEP-able. Small
enhancements or patches often don't need a PEP and can be injected
into the Python development work flow with a patch submission to
the SourceForge patch manager[2] or feature request tracker[3].
The champion then emails the PEP editor with a proposed title and
a rough, but fleshed out, draft of the PEP.
The PEP champion then emails the PEP editor with a proposed title
and a rough, but fleshed out, draft of the PEP. This draft must
be written in PEP style as described below.
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 <guido@python.org>) is the
final arbitrator of the latter.
or not in keeping with the Python philosophy. The BDFL
(Benevolent Dictator for Life, Guido van Rossum
<guido@python.org>) can be consulted during the approval phase,
and is the final arbitrator of the draft's PEP-ability.
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 author of the PEP is then responsible for posting the PEP to
the community forums, and marshaling community support for it. As
updates are necessary, the PEP author can check in new versions if
they have CVS commit permissions, or can email new PEP versions to
the PEP editor for committing.
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.
Standards track PEPs 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.
Standards Track PEPs 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.
discussed on python-list@python.org and/or python-dev@python.org
will not be accepted. 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
@ -102,9 +107,13 @@ PEP Workflow
it was not a good idea. It is still important to have a record of
this fact.
PEPs can also be replaced by a different PEP, rendering the
original obsolete. This is intended for Informational PEPs, where
version 2 of an API can replace version 1.
PEP work flow is as follows:
Draft -> Accepted -> Final
Draft -> Accepted -> Final -> Replaced
^
+----> Rejected
v
@ -118,24 +127,24 @@ What belongs in a successful PEP?
Each PEP should have the following parts:
1. Title -- a short, descriptive title
1. Preamble -- RFC822 style headers containing meta-data about the
PEP, including the PEP number, a short descriptive title, the
names contact info for each author, etc.
2. Author(s) -- names and contact info for each author
2. Abstract -- a short (~200 word) description of the technical
issue being addressed.
3. Abstract -- a short (~200 word) description of the technical issue
being addressed
4. Copyright/public domain -- Each PEP must either be explicitly
3. Copyright/public domain -- Each PEP must either be explicitly
labelled in the public domain or the Open Publication
License[2].
License[4].
5. Specification -- The technical specification should describe
4. 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
5. 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
@ -145,8 +154,8 @@ What belongs in a successful PEP?
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
6. 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.
@ -160,51 +169,61 @@ 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].
converts the plain text PEP to HTML for viewing on the web[5].
Each PEP begins with an RFC822 style header section. Required
headers are as follows, and must appear in this order:
Each PEP must begin with an RFC822 style header preamble. The
headers must appear in the following order. Headers marked with
`*' are optional and are described below. All other headers are
required.
PEP: <pep number>
Title: <pep title>
Version: <cvs version string>
Author: <list of authors' email and real name>
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Final>
Type: <Informational | Standards Track>
Created: <date created on, in dd-mmm-yyyy format>
* Python-Version: <version number>
Post-History: <dates of postings to python-list and python-dev>
* Replaces: <pep number>
* Replaced-By: <pep number>
Standards track PEPs should additionally have a Python-Version:
header which indicates the version of Python that the feature will
be released with.
Standards track PEPs must have a Python-Version: header which
indicates the version of Python that the feature will be released
with. Informational PEPs do not need a Python-Version: header.
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.
list or URL where the PEP is being discussed. No Discussions-To:
header is necessary if the PEP is being discussed privately with
the author, or on the python-list or python-dev email mailing
lists.
PEP headings should begin in column zero and should be
capitalized. The body of each section should be indented 4
PEPs may also have a Replaced-By: header indicating that a PEP has
been rendered obsolete by a later document; the value is the
number of the PEP that replaces the current document. The newer
PEP must have a Replaces: header containing the number of the PEP
that it rendered obsolete.
PEP headings must begin in column zero and the initial letter of
each word must be capitalized as in book titles. Acronyms should
be in all capitals. The body of each section must 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.
make the text readable. You must 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.
Tab characters must never appear in the document at all. A PEP
should include the Emacs stanza included by example in this PEP.
A PEP must contain a Copyright heading, and it is strongly
A PEP must contain a Copyright section, 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
@ -214,9 +233,13 @@ References and Footnotes
http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/python/nondist/peps/?cvsroot=python
[2] http://www.opencontent.org/openpub/
[2] http://sourceforge.net/tracker/?group_id=5470&atid=305470
[3] The script referred to here is pep2html.py, which lives in
[3] http://sourceforge.net/tracker/?atid=355470&group_id=5470&func=browse
[4] http://www.opencontent.org/openpub/
[5] 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.
@ -224,6 +247,10 @@ References and Footnotes
http://python.sourceforge.net/peps/
Copyright
This document has been placed in the public domain.
Local Variables: