aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'glep-0001.txt')
-rw-r--r--glep-0001.txt366
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.