Rename all GLEPs to .rst

1 files changed, 393 insertions, 0 deletions

diff --git a/glep-0001.rst b/glep-0001.rst
new file mode 100644
index 0000000..57c6c35
--- /dev/null
+++ b/glep-0001.rst
@@ -0,0 +1,393 @@
+GLEP: 1
+Title: GLEP Purpose and Guidelines
+Version: $Revision$
+Last-Modified: $Date$
+Author: Grant Goodyear <g2boojum@gentoo.org>,
+        Michał Górny <mgorny@gentoo.org>,
+        Ulrich Müller <ulm@gentoo.org>
+Status: Active
+Type: Informational
+Content-Type: text/x-rst
+Created: 31-May-2003
+Post-History: 1-Jun-2003, 2-Jul-2003, 19-Jan-2008, 05-Jun-2008, 09-Mar-2011,
+              14-Dec-2013
+
+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 in a VCS, their revision
+history is the historical record of the feature proposal [#VCS]_. For older
+GLEPs, the base repository may provide an approximate history of the changes.
+The original changes can still be found in [#CVS]_ for changes up to June 2013
+and/or [#WIKI]_ for changes onwards up to September 2017.
+
+
+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 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. 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 focused the GLEP, the more successful it tends to be.  The GLEP editors
+reserve the right to reject GLEP proposals if they appear too unfocused or
+too broad.  If in doubt, split your GLEP into several well-focused 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 files a bug on Bugzilla in the GLEP product, under
+the "New GLEP submissions" component of the "Documentation" product
+and prepares a rough, but fleshed out, draft of the GLEP on a dedicated
+branch of the GLEP repository or a private fork of that repository.  This
+draft must be written in GLEP style as described below and in GLEP 2.
+
+If the GLEP editors accept the GLEP, they 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 merge the initial draft of the GLEP
+to the master branch of the repository.  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@lists.gentoo.org mailing list (for technical GLEPs)
+or the gentoo-project@lists.gentoo.org mailing list (for non-technical GLEPs)
+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 or gentoo-project mailing list (and additionally to
+the Gentoo Linux forums [#FORUMS]_ if they so desire), and marshaling community
+support for it.  As updates are necessary, the GLEP author should request
+merging changes to the master branch from a GLEP editor.
+
+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
+the mailing lists and 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 Gentoo Council
+[#COUNCIL]_ that it is ready for review by way of the appropriate mailing
+list.  GLEPs are then reviewed at a Council meeting where the may be approved
+or rejected outright, or sent back to the author(s) for revision.  This
+generally should be done a few weeks in advance of the actual review so as to
+avoid the appearance of "slipping" a GLEP in without proper public review
+by the Gentoo developer community. Any revisions should be added to the GLEP
+bug on Bugzilla.
+
+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.
+
+The "Withdrawn" status is similar - it means that the GLEP author has decided
+that the GLEP is actually a bad idea, or has accepted that a competing
+proposal is a better alternative.
+
+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).
+
+If a "Final" GLEP becomes obsolete and requires no explicit replacement,
+it can be marked "Moribund".
+
+GLEP work flow is as follows::
+
+    Draft -> Accepted -> Final -> Replaced
+      ^                    |
+      +----> Rejected      +----> Moribund
+      |
+      +----> Withdrawn
+      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 2822 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.
+
+   Described further below.
+
+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 -- Every new GLEP must be explicitly labelled
+   as licensed under the Creative Commons Attribution-ShareAlike (CC-BY-SA)
+   license, version 3.0 [#CC-BY-SA3.0]_. Older GLEPs in the public domain
+   should be relicensed to CC-BY-SA 3.0 when they are updated.
+   GLEPs released under the Open Publication License (OPL) may remain
+   as-is, but are strongly encouraged to be relicensed under CC-BY-SA
+   3.0 with the consent of all authors.
+
+
+GLEP Formating and Template
+===========================
+
+GLEPs are written in ReStructuredText markup [#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.  GLEP 2 contains a boilerplate
+template [#GLEP2]_ for use with ReStructuredText GLEPs.
+
+For best interoperability, the GLEPs using ReStructuredText format must use
+``.rst`` file suffix.
+
+
+GLEP Header
+===========
+
+Every GLEP has certain attributes associated with it. When a GLEP is sent
+to the mailing lists for discussion, it should begin with an RFC 2822 style
+header preamble between two triple-dashed lines.  The headers must appear
+in the following order.  For interoperability, the header preamble should also
+conform to the YAML standard [#YAML]_.  Headers marked with "*" are optional.
+All other headers are required.
+
+::
+
+    ---
+    GLEP: <glep number>
+    Title: <glep title>
+    Author: <list of authors' real names and optionally, email addrs>
+    Type: <Informational | Standards Track>
+    Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
+             Final | Replaced | Moribund>
+    Version: <major>[.<minor>]
+    Created: <date created on>
+    Last-Modified: <date of last update>
+    Post-History: <dates of postings to mailing lists>
+    Content-Type: <text/x-rst>
+  * Requires: <glep numbers>
+  * 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.  Anybody who submits changes to
+the GLEP should be added to this field.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.
+
+The Type header specifies the type of GLEP: Informational or Standards
+Track.
+
+The Version field specifies the current version of the GLEP. The Version
+consists of a major version, optionally followed by a minor version (if
+non-zero). Every GLEP starts at version 1 which is successively incremented
+as changes are merged to the GLEP.
+
+The major version number should be incremented (and minor reset to zero)
+whenever the meaning of the GLEP changes. The minor version number should
+be incremented for changes that do not affect the basic meaning (e.g.
+clarifications, reference implementation updates). Editorial changes should
+be merged without increasing the version.
+
+The Created header records the date that the GLEP was assigned a number,
+Last-Modified specifies the date that the GLEP was last updated in the master
+branch, while Post-History is used to record the dates of when new versions
+of the GLEP are posted to the appropriate mailing list.  All three headers
+should be in ISO 8601 ``yyyy-mm-dd`` format, e.g. 2001-08-14.
+
+The format of a GLEP is specified with a Content-Type header, which
+must be "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 [#GLEP2]_).
+
+GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP
+depends on.
+
+GLEPs may also have a Replaces header indicating that a GLEP is meant
+to replace one or more older GLEPs.  Once such a GLEP is accepted, a matching
+Replaced-By should be added to all replaced GLEPs and their status should
+be updated to Replaced.
+
+
+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
+or comment on the GLEP bug. For more mature, or finished GLEPs you may want
+to submit corrections to the Gentoo Linux bugzilla [#BUGS]_ under the "GLEP
+Changes" component of the "Documentation" product so that your changes don't get
+lost. Be sure to CC the GLEP author on the bug. When in doubt about where
+to send your changes, please check first with the GLEP author and/or GLEP
+editors.
+
+GLEP authors must have a GLEP editor merge their changes to the master branch,
+as the write access is restricted to GLEP editors in order to protect
+the integrity of the GLEPs.
+
+Any major updates to GLEPs (that is, those that change the content of
+the GLEP rather than just fixing typos or adding small clarifications)
+should be approved by the Gentoo Council before being merged.
+
+
+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@gentoo.org>, or comment on the GLEP bug.  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
+
+.. [#VCS] https://gitweb.gentoo.org/proj/glep.git
+
+.. [#CVS] https://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo/xml/htdocs/proj/en/glep/
+
+.. [#WIKI] https://wiki.gentoo.org/index.php?title=Special%3AAllPages&from=&to=&namespace=550
+
+.. [#BUGS] http://bugs.gentoo.org
+
+.. [#FORUMS] http://forums.gentoo.org
+
+.. [#COUNCIL] http://www.gentoo.org/proj/en/glep/glep-0039.html
+
+.. [#CC-BY-SA3.0] http://creativecommons.org/licenses/by-sa/3.0/
+
+.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html
+
+.. [#DOCUTILS] http://docutils.sourceforge.net/
+
+.. [#GLEP2] http://glep.gentoo.org/glep-0002.html
+
+.. [#YAML] http://yaml.org/
+
+
+Copyright
+=========
+
+This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
+Unported License.  To view a copy of this license, visit
+http://creativecommons.org/licenses/by-sa/3.0/.