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
index 0000000..80bffd0
--- /dev/null
+++ b/glep-1.txt
@@ -0,0 +1,410 @@
+GLEP: 1
+Title: GLEP Purpose and Guidelines
+Version: $Revision: 1.1 $
+Last-Modified: $Date: 2003/05/31 15:18:03 $
+Author: Grant Goodyear
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 31 May 2003
+Post-History: 
+
+
+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
+[1]_.
+
+
+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 <peps@python.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 <peps@python.org> 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. python-list@python.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
+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.  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
+here.
+
+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
+revisions.
+
+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 [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
+fact.
+
+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
+      v
+    Deferred
+
+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
+reStructuredText_.
+
+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 [3]_ you can use to get started writing your
+plaintext GLEP.
+
+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 [4]_ for use with
+reStructuredText GLEPs.
+
+There is a Python script that converts both styles of GLEPs to HTML for
+viewing on the web [5]_.  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 <address@dom.ain>
+
+if the email address is included, and just
+
+    Random J. User
+
+if the address is not given.  For historical reasons the format
+"address@dom.ain (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
+harvesters.
+
+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
+Track.
+
+The format of a GLEP is specified with a Content-Type header.  The
+acceptable values are "text/plain" for plaintext GLEPs (see GLEP 9 [3]_)
+and "text/x-rst" for reStructuredText GLEPs (see GLEP 12 [4]_).
+Plaintext ("text/plain") is the default if no Content-Type header is
+present.
+
+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
+obsolete.
+
+
+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
+
+for details.
+
+
+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 <peps@python.org>.  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
+.. [1] 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
+   http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/nondist/peps/
+
+.. [2] GLEP 2, Procedure for Adding New Modules, Faassen
+   (http://www.python.org/peps/pep-0002.html)
+
+.. [3] GLEP 9, Sample Plaintext GLEP Template, Warsaw
+   (http://www.python.org/peps/pep-0009.html)
+
+.. [4] GLEP 12, Sample reStructuredText GLEP Template, Goodger, Warsaw
+   (http://www.python.org/peps/pep-0012.html)
+
+.. [5] 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:
+   http://sourceforge.net/tracker/?group_id=5470&atid=305470
+
+.. _feature request tracker:
+   http://sourceforge.net/tracker/?atid=355470&group_id=5470&func=browse
+
+.. _Open Publication License: http://www.opencontent.org/openpub/
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+.. _bug manager:
+   http://sourceforge.net/tracker/?group_id=5470&atid=105470
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.