The first two proposed GLEPs + some utility files.

1 files changed, 366 insertions, 0 deletions

diff --git a/glep-0001.txt b/glep-0001.txt
new file mode 100644
index 0000000..89296e9
--- /dev/null
+++ b/glep-0001.txt
@@ -0,0 +1,366 @@
+GLEP: 1
+Title: GLEP Purpose and Guidelines
+Version: $Revision: 1.1 $
+Last-Modified: $Date: 2003/06/01 04:33:49 $
+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 *significant* new
+features, for collecting community input on an issue, and for
+documenting the design decisions that have gone into Gentoo Linux.  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 Gentoo Linux.  An Informational GLEP describes
+provides general guidelines or information
+to the Gentoo Linux community, but does not propose a new feature.
+Informational GLEPs do not necessarily represent a Gentoo Linux 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 Grant Goodyear and hopefully somebody
+else.  Please send
+all GLEP-related email to <glep@gentoo.org>.
+
+The GLEP process begins with a new idea for Gentoo Linux.  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 Gentoo Linux development
+work flow with an enhancement "bug" submitted to the Gentoo Linux bugzilla_.
+
+The GLEP champion then emails the GLEP editor <glep@gentoo.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 (a better name would be nice here -- suggestions?) 
+or Informational, give it status "Draft", and
+create and check-in the initial draft of the GLEP.  The GLEP editors 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 Gentoo Linux philosophy.  
+
+If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to
+the gentoo-dev@gentoo.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
+gentoo-dev mailing list and to the `Gentoo Linux 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
+editors for committing.
+
+Standards Track GLEPs consist 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
+gentoo-dev@gentoo.org and/or the `Gentoo Linux forums`_ 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 specific forums thread
+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 editors
+that it is ready for review.  GLEPs are reviewed by the Gentoo Linux
+Chief Architect or Development Manager, who may accept or reject a GLEP
+outright, 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 Chief Architect or the Development
+Manager 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 distrubution unduly.  Finally, a proposed enhancement must 
+satisfy the philosophy of Gentoo Linux.
+
+Once a GLEP has been accepted, the reference implementation must be
+completed.  When the reference implementation is complete and accepted,
+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
+a policy, for example, 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. Motivation -- The motivation is critical for GLEPs that want to
+   change the Gentoo Linux functionality.  It should clearly explain why the
+   existing functionality or policy is inadequate to address the
+   problem that the GLEP solves.  GLEP submissions without sufficient
+   motivation may be rejected outright.
+
+5. Specification -- The technical specification should describe the
+   specific areas of Gentoo Linux that would be touched by this GLEP.  
+   If new functionality is being introduced, what packages will that
+   functionality affect?  If new policy, who will be affected?
+
+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 distributions.
+
+   The rationale should provide evidence of consensus within the
+   community and discuss important objections or concerns raised
+   during discussion.
+
+7. Backwards Compatibility -- All GLEPs 
+   must include a section describing any issues of backwards
+   incompatibilities and their severity.  
+   The GLEP must explain how the
+   author proposes to deal with these incompatibilities.  
+   (Even if there are none, this section should be included to clearly
+   state that fact.)
+   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 or significantly modifying ebuilds.
+
+
+GLEP Formating and Template
+===========================
+
+GLEPs are written in a just-barely-marked-up version of plain, ASCII text
+called ReStructuredText_ that is then converted to HTML using Docutils_.
+Using ReStructuredText_ GLEPs allows for rich markup that is still quite easy
+to read, but results in much better-looking and more functional HTML.
+Moreover, it should be straightforward to convert GLEPs to `guide xml`_
+if needed.
+GLEP 2 contains a boilerplate template [4]_ for use with
+reStructuredText GLEPs.
+
+
+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: <glep number>
+    Title: <glep 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: <glep numbers>
+    Created: <date created on, in dd-mmm-yyyy format>
+    Post-History: <dates of postings to gentoo-dev>
+  * Replaces: <glep number>
+  * Replaced-By: <glep 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.  
+
+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 gentoo-dev 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, which
+for now should always read "text/x-rst" for reStructuredText GLEPs (see GLEP 2 [4]_).
+
+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 gentoo-dev.  Both
+headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001.
+
+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 Gentoo Linux bugzilla_ 
+so that your changes don't get
+lost.  If the GLEP author is a Gentoo Linux 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 editors.
+
+GLEP authors who are also Gentoo Linux developers can update the GLEPs themselves
+by using "cvs commit" to commit their changes.  
+
+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 <glep@gentoo.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 Gentoo Linux viewcvs web site at
+   http://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-x86/glep/
+
+.. [4] GLEP 2, Sample reStructuredText GLEP Template, Goodyear, Goodger, Warsaw
+   (http://www.gentoo.org/glep/glep-0002.html)
+
+
+.. _bugzilla: http://bugs.gentoo.org
+
+.. _Gentoo Linux forums: http://forums.gentoo.org
+
+.. _Open Publication License: http://www.opencontent.org/openpub/
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+.. _guide xml: http://www.gentoo.org/doc/en/xml-guide.xml
+
+.. _Docutils: http://docutils.sourceforge.net/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.