[gentoo-commits] gentoo commit in xml/htdocs/proj/en/glep: glep-0001.txt

[Piotr Jaroszynski (peper)]

peper       08/01/05 03:05:07

  Modified:             glep-0001.txt
  Log:
  Fix GLEP 01 txt.

Revision  Changes    Path
1.10                 xml/htdocs/proj/en/glep/glep-0001.txt

file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0001.txt?rev=1.10&view=markup
plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0001.txt?rev=1.10&content-type=text/plain
diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/proj/en/glep/glep-0001.txt?r1=1.9&r2=1.10

Index: glep-0001.txt
===================================================================
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/glep/glep-0001.txt,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -r1.9 -r1.10
--- glep-0001.txt	5 Jan 2008 02:36:35 -0000	1.9
+++ glep-0001.txt	5 Jan 2008 03:05:07 -0000	1.10
@@ -0,0 +1,356 @@
+GLEP: 1
+Title: GLEP Purpose and Guidelines
+Version: $Revision: 1.10 $
+Last-Modified: $Date: 2008/01/05 03:05:07 $
+Author: Grant Goodyear <g2boojum@g.o>
+Status: Active
+Type: Informational
+Content-Type: text/x-rst
+Created: 31-May-2003
+Post-History: 1-Jun-2003, 2-Jul-2003
+
+
+Credits
+=======
+
+The GLEP concept, and, in fact, much of the text of this document,
+is liberally stolen from Python's [#Python]_ PEPs
+[#PEPS]_, especially
+PEP-0001 [#PEP1]_ by Barry A. Warsaw, Jeremy Hylton, and David Goodger.
+
+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 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
+[#CVS]_.
+
+
+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 Alastair Tse.  Please send all
+GLEP-related email to <glep@g.o>.
+
+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 editors
+reserve 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 [#BUGS]_.
+
+The GLEP champion then emails the GLEP editors <glep@g.o> 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 accepts the GLEP, 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@g.o 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 [#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@g.o and/or the Gentoo Linux forums [#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 appropriate Gentoo
+Manager [#MANAGER]_, who may approve or reject a GLEP outright, or
+send it back to the author(s) for revision.  For a GLEP that is pre-determined
+to be approvable (e.g., it is an obvious win as-is and/or its implementation
+has already been checked in) the appropriate Gentoo Manager [#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 approved 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 distribution 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 (where version 2 of a policy, for example, might 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. Motivation -- The motivation is critical for GLEPs that want to
+   modify 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.
+
+4. 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?
+
+5. 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.
+
+6. 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.
+
+7. 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.
+
+8. 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 [#OPL].
+
+
+GLEP Formating and Template
+===========================
+
+GLEPs are written either in Gentoo Linux Guide-XML [#GUIDEXML]_ or in
+a just-barely-marked-up version of plain ASCII text
+called ReStructuredText [#ReSTHOME]_ that is then converted to HTML using
+Docutils [#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
+Gentoo Linux guide xml [#GUIDEXML]_ if needed.  GLEP 2 contains a boilerplate
+template [#ReST]_ for use with ReStructuredText GLEPs.
+
+
+GLEP Header Preamble
+====================
+
+Each GLEP must begin with an RFC 2822 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@×××.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 list.  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 
+should read "text/xml" for Gentoo Guide XML or 
+"text/x-rst" for ReStructuredText GLEPs (see GLEP 2
+[#ReST]_).
+
+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 [#BUGS]_ 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 editors.
+
+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 editors
+<glep@g.o>.  If the original author doesn't respond to email in a
+timely manner, the GLEP editors will make a unilateral decision (it's not like
+such decisions can't be reversed :).
+
+
+References and Footnotes
+========================
+
+.. [#PYTHON] http://www.python.org
+
+.. [#PEPS] http://www.python.org/peps
+
+.. [#PEP1] http://www.python.org/peps/pep-0001.html
+
+.. [#CVS] 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://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo/xml/htdocs/proj/en/glep/
+
+.. [#ReST] GLEP 2, Sample ReStructuredText GLEP Template, 
+   (http://glep.gentoo.org/glep-0002.html)
+
+.. [#BUGS] http://bugs.gentoo.org
+
+.. [#FORUMS] http://forums.gentoo.org
+
+.. [#MANAGER] http://www.gentoo.org/doc/en/management-structure.xml
+
+.. [#OPL] http://www.opencontent.org/openpub/
+
+.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html
+
+.. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml
+
+.. [#DOCUTILS] http://docutils.sourceforge.net/
+
+
+Copyright
+=========
+
+This document has been placed in the public domain.



-- 
gentoo-commits@g.o mailing list