diff options
Diffstat (limited to 'glep-0001.rst')
-rw-r--r-- | glep-0001.rst | 393 |
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/. |