[Python-checkins] CVS: python/nondist/peps pep-0001.txt,1.1,1.2
Barry Warsaw
python-dev@python.org
Tue, 25 Jul 2000 10:59:11 -0700
Update of /cvsroot/python/python/nondist/peps
In directory slayer.i.sourceforge.net:/tmp/cvs-serv23767
Modified Files:
pep-0001.txt
Log Message:
Fleshed out the bulk of the guidelines, after internal discussion
among the PEP authors and the BDFL.
Index: pep-0001.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0001.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** pep-0001.txt 2000/07/13 06:33:08 1.1
--- pep-0001.txt 2000/07/25 17:59:08 1.2
***************
*** 1,7 ****
PEP: 1
! Title: PEP Guidelines
Version: $Revision$
! Owner: bwarsaw@beopen.com (Barry A. Warsaw)
! Status: Incomplete
--- 1,207 ----
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 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/
!