|author||Grant Goodyear <firstname.lastname@example.org>||2003-05-31 15:18:03 +0000|
|committer||Grant Goodyear <email@example.com>||2003-05-31 15:18:03 +0000|
Proposed "Gentoo Linux Enhancement Proposals", if approved.
1 files changed, 410 insertions, 0 deletions
diff --git a/glep-1.txt b/glep-1.txt
new file mode 100644
@@ -0,0 +1,410 @@
+Title: GLEP Purpose and Guidelines
+Version: $Revision: 1.1 $
+Last-Modified: $Date: 2003/05/31 15:18:03 $
+Author: Grant Goodyear
+Created: 31 May 2003
+What is a GLEP?
+GLEP stands for "Gentoo Linux Enhancement Proposal". A GLEP is a design
+document providing information to the Gentoo Linux community, or describing
+a new feature for Gentoo Linux. (The GLEP concept, and, in fact,
+much of the text of this document, is liberally stolen from Python's
+`PEP-0001`_.) The GLEP should provide a concise technical
+specification of the feature and rationale for the feature.
+We intend GLEPs 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 GLEP
+author is responsible for building consensus within the community and
+documenting dissenting opinions.
+Because the GLEPs are maintained as text files under CVS control, their
+revision history is the historical record of the feature proposal
+Kinds of GLEPs
+There are two kinds of GLEPs. A Standards Track GLEP describes a new
+feature or implementation for Python. An Informational GLEP describes
+a Python design issue, or provides general guidelines or information
+to the Python community, but does not propose a new feature.
+Informational GLEPs do not necessarily represent a Python community
+consensus or recommendation, so users and implementors are free to
+ignore Informational GLEPs or follow their advice.
+GLEP Work Flow
+The GLEP editors assign GLEP numbers and change their status. The
+current GLEP editors are David Goodger and Barry Warsaw. Please send
+all GLEP-related email to <firstname.lastname@example.org>.
+The GLEP process begins with a new idea for Python. It is highly
+recommended that a single GLEP contain a single key proposal or new
+idea. The more focussed the GLEP, the more successful it tends to
+be. The GLEP editor reserves the right to reject GLEP proposals if they
+appear too unfocussed or too broad. If in doubt, split your GLEP into
+several well-focussed ones.
+Each GLEP must have a champion -- someone who writes the GLEP using the
+style and format described below, shepherds the discussions in the
+appropriate forums, and attempts to build community consensus around
+the idea. The GLEP champion (a.k.a. Author) should first attempt to
+ascertain whether the idea is GLEP-able. Small enhancements or patches
+often don't need a GLEP and can be injected into the Python development
+work flow with a patch submission to the SourceForge `patch manager`_
+or `feature request tracker`_.
+The GLEP champion then emails the GLEP editor <email@example.com> with a
+proposed title and a rough, but fleshed out, draft of the GLEP. This
+draft must be written in GLEP style as described below.
+If the GLEP editor approves, he will assign the GLEP a number, label it
+as Standards Track or Informational, give it status "Draft", and
+create and check-in the initial draft of the GLEP. The GLEP editor will
+not unreasonably deny a GLEP. Reasons for denying GLEP status include
+duplication of effort, being technically unsound, not providing proper
+motivation or addressing backwards compatibility, or not in keeping
+with the Python philosophy. The BDFL (Benevolent Dictator for Life,
+Guido van Rossum) can be consulted during the approval phase, and is
+the final arbitrator of the draft's GLEP-ability.
+If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to
+the comp.lang.python newsgroup (a.k.a. firstname.lastname@example.org mailing
+list) to help flesh it out, gain feedback and consensus from the
+community at large, and improve the GLEP for re-submission.
+The author of the GLEP is then responsible for posting the GLEP to the
+community forums, and marshaling community support for it. As updates
+are necessary, the GLEP author can check in new versions if they have
+CVS commit permissions, or can email new GLEP versions to the GLEP
+editor for committing.
+Standards Track GLEPs consists of two parts, a design document and a
+reference implementation. The GLEP should be reviewed and accepted
+before a reference implementation is begun, unless a reference
+implementation will aid people in studying the GLEP. Standards Track
+GLEPs must include an implementation -- in the form of code, patch, or
+URL to same -- before it can be considered Final.
+GLEP authors are responsible for collecting community feedback on a GLEP
+before submitting it for review. A GLEP that has not been discussed on
+email@example.com and/or firstname.lastname@example.org will not be
+accepted. However, wherever possible, long open-ended discussions on
+public mailing lists should be avoided. Strategies to keep the
+discussions efficient include, setting up a separate SIG mailing list
+for the topic, having the GLEP author accept private comments in the
+early design phases, etc. GLEP authors should use their discretion
+Once the authors have completed a GLEP, they must inform the GLEP editor
+that it is ready for review. GLEPs are reviewed by the BDFL and his
+chosen consultants, who may accept or reject a GLEP or send it back to
+the author(s) for revision. For a GLEP that is pre-determined to be
+acceptable (e.g., it is an obvious win as-is and/or its implementation
+has already been checked in) the BDFL may also initiate a GLEP review,
+first notifying the GLEP author(s) and giving them a chance to make
+For a GLEP to be accepted it must meet certain minimum criteria. It
+must be a clear and complete description of the proposed enhancement.
+The enhancement must represent a net improvement. The proposed
+implementation, if applicable, must be solid and must not complicate
+the interpreter unduly. Finally, a proposed enhancement must be
+"pythonic" in order to be accepted by the BDFL. (However, "pythonic"
+is an imprecise term; it may be defined as whatever is acceptable to
+the BDFL. This logic is intentionally circular.) See GLEP 2 _ for
+standard library module acceptance criteria.
+Once a GLEP 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 GLEP can also be assigned status "Deferred". The GLEP author or
+editor can assign the GLEP this status when no progress is being made
+on the GLEP. Once a GLEP is deferred, the GLEP editor can re-assign it
+to draft status.
+A GLEP 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
+GLEPs can also be replaced by a different GLEP, rendering the original
+obsolete. This is intended for Informational GLEPs, where version 2 of
+an API can replace version 1.
+GLEP work flow is as follows::
+ Draft -> Accepted -> Final -> Replaced
+ +----> Rejected
+Some Informational GLEPs may also have a status of "Active" if they are
+never meant to be completed. E.g. GLEP 1 (this GLEP).
+What belongs in a successful GLEP?
+Each GLEP should have the following parts:
+1. Preamble -- RFC 822 style headers containing meta-data about the
+ GLEP, including the GLEP number, a short descriptive title (limited
+ to a maximum of 44 characters), the names, and optionally the
+ contact info for each author, etc.
+2. Abstract -- a short (~200 word) description of the technical issue
+ being addressed.
+3. Copyright/public domain -- Each GLEP must either be explicitly
+ labelled as placed in the public domain (see this GLEP as an
+ example) or licensed under the `Open Publication License`_.
+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, Jython, Python .NET).
+5. Motivation -- The motivation is critical for GLEPs that want to
+ change the Python language. It should clearly explain why the
+ existing language specification is inadequate to address the
+ problem that the GLEP solves. GLEP submissions without sufficient
+ motivation may be rejected outright.
+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. Backwards Compatibility -- All GLEPs that introduce backwards
+ incompatibilities must include a section describing these
+ incompatibilities and their severity. The GLEP must explain how the
+ author proposes to deal with these incompatibilities. GLEP
+ submissions without a sufficient backwards compatibility treatise
+ may be rejected outright.
+8. Reference Implementation -- The reference implementation must be
+ completed before any GLEP is given status "Final", but it need not
+ be completed before the GLEP 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.
+GLEP Formats and Templates
+There are two GLEP formats available to authors: plaintext and
+Plaintext GLEPs are written in plain ASCII text, contain minimal
+structural markup, and should adhere to a rigid style. GLEP 9 contains
+a boilerplate template _ you can use to get started writing your
+ReStructuredText_ GLEPs allow for rich markup that is still quite easy
+to read, but results in much better-looking and more functional HTML.
+GLEP 12 contains a boilerplate template _ for use with
+There is a Python script that converts both styles of GLEPs to HTML for
+viewing on the web _. Parsing and conversion of plaintext GLEPs is
+self-contained within the script. reStructuredText GLEPs are parsed
+and converted by Docutils_ code called from the script.
+GLEP Header Preamble
+Each GLEP must begin with an RFC 822 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. ::
+ GLEP: <pep number>
+ Title: <pep title>
+ Version: <cvs version string>
+ Last-Modified: <cvs date string>
+ Author: <list of authors' real names and optionally, email addrs>
+ * Discussions-To: <email address>
+ Status: <Draft | Active | Accepted | Deferred | Rejected |
+ Final | Replaced>
+ Type: <Informational | Standards Track>
+ * Content-Type: <text/plain | text/x-rst>
+ * Requires: <pep numbers>
+ 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>
+The Author header lists the names, and optionally the email addresses
+of all the authors/owners of the GLEP. The format of the Author header
+value must be
+ Random J. User <email@example.com>
+if the email address is included, and just
+ Random J. User
+if the address is not given. For historical reasons the format
+"firstname.lastname@example.org (Random J. User)" may appear in a GLEP, however new
+GLEPs must use the mandated format above, and it is acceptable to
+change to this format when GLEPs are updated.
+If there are multiple authors, each should be on a separate line
+following RFC 2822 continuation line conventions. Note that personal
+email addresses in GLEPs will be obscured as a defense against spam
+While a GLEP is in private discussions (usually during the initial
+Draft phase), a Discussions-To header will indicate the mailing list
+or URL where the GLEP is being discussed. No Discussions-To header is
+necessary if the GLEP is being discussed privately with the author, or
+on the python-list or python-dev email mailing lists. Note that email
+addresses in the Discussions-To header will not be obscured.
+The Type header specifies the type of GLEP: Informational or Standards
+The format of a GLEP is specified with a Content-Type header. The
+acceptable values are "text/plain" for plaintext GLEPs (see GLEP 9 _)
+and "text/x-rst" for reStructuredText GLEPs (see GLEP 12 _).
+Plaintext ("text/plain") is the default if no Content-Type header is
+The Created header records the date that the GLEP was assigned a
+number, while Post-History is used to record the dates of when new
+versions of the GLEP are posted to python-list and/or python-dev. Both
+headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+Standards Track GLEPs must have a Python-Version header which indicates
+the version of Python that the feature will be released with.
+Informational GLEPs do not need a Python-Version header.
+GLEPs may have a Requires header, indicating the GLEP numbers that this
+GLEP depends on.
+GLEPs may also have a Replaced-By header indicating that a GLEP has been
+rendered obsolete by a later document; the value is the number of the
+GLEP that replaces the current document. The newer GLEP must have a
+Replaces header containing the number of the GLEP that it rendered
+Reporting GLEP Bugs, or Submitting GLEP Updates
+How you report a bug, or submit a GLEP update depends on several
+factors, such as the maturity of the GLEP, the preferences of the GLEP
+author, and the nature of your comments. For the early draft stages
+of the GLEP, it's probably best to send your comments and changes
+directly to the GLEP author. For more mature, or finished GLEPs you may
+want to submit corrections to the SourceForge `bug manager`_ or better
+yet, the SourceForge `patch manager`_ so that your changes don't get
+lost. If the GLEP author is a SF developer, assign the bug/patch to
+him, otherwise assign it to the GLEP editor.
+When in doubt about where to send your changes, please check first
+with the GLEP author and/or GLEP editor.
+GLEP authors who are also SF committers, can update the GLEPs themselves
+by using "cvs commit" to commit their changes. Remember to also push
+the formatted GLEP text out to the web by doing the following::
+ % python pep2html.py -i NUM
+where NUM is the number of the GLEP you want to push out. See ::
+ % python pep2html.py --help
+Transferring GLEP Ownership
+It occasionally becomes necessary to transfer ownership of GLEPs to a
+new champion. In general, we'd like to retain the original author as
+a co-author of the transferred GLEP, but that's really up to the
+original author. A good reason to transfer ownership is because the
+original author no longer has the time or interest in updating it or
+following through with the GLEP process, or has fallen off the face of
+the 'net (i.e. is unreachable or not responding to email). A bad
+reason to transfer ownership is because you don't agree with the
+direction of the GLEP. We try to build consensus around a GLEP, but if
+that's not possible, you can always submit a competing GLEP.
+If you are interested in assuming ownership of a GLEP, send a message
+asking to take over, addressed to both the original author and the GLEP
+editor <email@example.com>. If the original author doesn't respond to
+email in a timely manner, the GLEP editor will make a unilateral
+decision (it's not like such decisions can't be reversed :).
+References and Footnotes
+.. _PEP-0001: http://www.python.org/peps/pep-0001.html
+..  This historical record is available by the normal CVS commands
+ for retrieving older revisions. For those without direct access to
+ the CVS tree, you can browse the current and past GLEP revisions via
+ the SourceForge web site at
+..  GLEP 2, Procedure for Adding New Modules, Faassen
+..  GLEP 9, Sample Plaintext GLEP Template, Warsaw
+..  GLEP 12, Sample reStructuredText GLEP Template, Goodger, Warsaw
+..  The script referred to here is pep2html.py, which lives in the
+ same directory in the CVS tree as the GLEPs themselves. Try
+ ``pep2html.py --help`` for details. The URL for viewing GLEPs on
+ the web is http://www.python.org/peps/.
+.. _patch manager:
+.. _feature request tracker:
+.. _Open Publication License: http://www.opencontent.org/openpub/
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _bug manager:
+This document has been placed in the public domain.