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

georg.brandl python-checkins at python.org
Wed Mar 23 21:23:15 CET 2011

• Previous message: [Python-checkins] peps: some content to start things off (maybe someone else will add to it...)
• Next message: [Python-checkins] peps: More explanation of feature requirements and mechanics of construction.
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

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: RevisionRevisionRevision -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
• 1. Author(s) -- names and contact info for each author
• 1. Abstract -- a short (~200 word) description of the technical issue

•   being addressed

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

•   labelled in the public domain or the Open Publication

•   License[1].

• 1. 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).

• 1. 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.

• 1. 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

• Previous message: [Python-checkins] peps: some content to start things off (maybe someone else will add to it...)
• Next message: [Python-checkins] peps: More explanation of feature requirements and mechanics of construction.
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

More information about the Python-checkins mailing list