diff options
Diffstat (limited to 'glep-0001.txt')
| -rw-r--r-- | glep-0001.txt | 381 |
1 files changed, 184 insertions, 197 deletions
diff --git a/glep-0001.txt b/glep-0001.txt index 89296e9..36c3f2e 100644 --- a/glep-0001.txt +++ b/glep-0001.txt @@ -1,7 +1,7 @@ GLEP: 1 Title: GLEP Purpose and Guidelines -Version: $Revision: 1.1 $ -Last-Modified: $Date: 2003/06/01 04:33:49 $ +Version: $Revision: 1.2 $ +Last-Modified: $Date: 2003/06/01 14:05:29 $ Author: Grant Goodyear Status: Draft Type: Informational @@ -10,14 +10,20 @@ Created: 31 May 2003 Post-History: +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 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 +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 @@ -28,47 +34,44 @@ 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]_. +[#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. +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 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_. +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 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. +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?) @@ -79,69 +82,59 @@ 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. +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. +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@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. +gentoo-dev@gentoo.org 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 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 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. This is intended for Informational GLEPs, where version 2 of -a policy, for example, can replace version 1. +obsolete (where version 2 of a policy, for example, might replace version 1). GLEP work flow is as follows:: @@ -151,8 +144,8 @@ GLEP work flow is as follows:: 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). +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? @@ -168,66 +161,59 @@ Each GLEP should have the following parts: 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 +3. 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. + 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 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. +GLEPs are written 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 822 style header preamble. The headers +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. :: @@ -264,100 +250,101 @@ 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. +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 -for now should always read "text/x-rst" for reStructuredText GLEPs (see GLEP 2 [4]_). +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 +[#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. +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 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. +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. +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. +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. +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 +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 :). +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>. 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 ======================== -.. _PEP-0001: http://www.python.org/peps/pep-0001.html +.. [#PYTHON] http://www.python.org -.. [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 +.. [#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://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo-x86/glep/ -.. [4] GLEP 2, Sample reStructuredText GLEP Template, Goodyear, Goodger, Warsaw +.. [#ReST] GLEP 2, Sample ReStructuredText GLEP Template, (http://www.gentoo.org/glep/glep-0002.html) +.. [#BUGS] http://bugs.gentoo.org -.. _bugzilla: http://bugs.gentoo.org - -.. _Gentoo Linux forums: http://forums.gentoo.org +.. [#FORUMS] http://forums.gentoo.org -.. _Open Publication License: http://www.opencontent.org/openpub/ +.. [#OPL] http://www.opencontent.org/openpub/ -.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html -.. _guide xml: http://www.gentoo.org/doc/en/xml-guide.xml +.. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml -.. _Docutils: http://docutils.sourceforge.net/ +.. [#DOCUTILS] http://docutils.sourceforge.net/ Copyright |