[Python-checkins] peps: Fleshed out the bulk of the guidelines, after internal discussion

Wed Mar 23 21:23:15 CET 2011

http://hg.python.org/peps/rev/be7150dbe20c
changeset: 45:be7150dbe20c
user: Barry Warsaw <barry at python.org>
date: Tue Jul 25 17:59:08 2000 +0000
summary:
 Fleshed out the bulk of the guidelines, after internal discussion
among the PEP authors and the BDFL.
files:
 pep-0001.txt | 206 ++++++++++++++++++++++++++++++++++++++-
 1 files changed, 203 insertions(+), 3 deletions(-)

diff --git a/pep-0001.txt b/pep-0001.txt
--- 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 at beopen.com (Barry A. Warsaw)
-Status: Incomplete
+Author: bwarsaw at beopen.com (Barry A. Warsaw),
+ jeremy at 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 at 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 at 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:
-- 
Repository URL: http://hg.python.org/peps
