| 1 | GLEP: 1 |
|
|
| 2 | Title: GLEP Purpose and Guidelines |
|
|
| 3 | Version: $Revision: 1.2 $ |
|
|
| 4 | Last-Modified: $Date: 2003/06/02 17:37:47 $ |
|
|
| 5 | Author: Grant Goodyear |
|
|
| 6 | Status: Draft |
|
|
| 7 | Type: Informational |
|
|
| 8 | Content-Type: text/x-rst |
|
|
| 9 | Created: 31 May 2003 |
|
|
| 10 | Post-History: |
|
|
| 11 | |
|
|
| 12 | |
|
|
| 13 | Credits |
|
|
| 14 | ======= |
|
|
| 15 | |
|
|
| 16 | The GLEP concept, and, in fact, much of the text of this document, |
|
|
| 17 | is liberally stolen from Python's [#Python]_ PEPs |
|
|
| 18 | [#PEPS]_, especially |
|
|
| 19 | PEP-0001 [#PEP1]_ by Barry A. Warsaw, Jeremy Hylton, and David Goodger. |
|
|
| 20 | |
|
|
| 21 | What is a GLEP? |
|
|
| 22 | =============== |
|
|
| 23 | |
|
|
| 24 | GLEP stands for "Gentoo Linux Enhancement Proposal". A GLEP is a design |
|
|
| 25 | document providing information to the Gentoo Linux community, or describing |
|
|
| 26 | a new feature for Gentoo Linux. The GLEP should provide a concise technical |
|
|
| 27 | specification of the feature and rationale for the feature. |
|
|
| 28 | |
|
|
| 29 | We intend GLEPs to be the primary mechanisms for proposing *significant* new |
|
|
| 30 | features, for collecting community input on an issue, and for |
|
|
| 31 | documenting the design decisions that have gone into Gentoo Linux. The GLEP |
|
|
| 32 | author is responsible for building consensus within the community and |
|
|
| 33 | documenting dissenting opinions. |
|
|
| 34 | |
|
|
| 35 | Because the GLEPs are maintained as text files under CVS control, their |
|
|
| 36 | revision history is the historical record of the feature proposal |
|
|
| 37 | [#CVS]_. |
|
|
| 38 | |
|
|
| 39 | |
|
|
| 40 | Kinds of GLEPs |
|
|
| 41 | ============== |
|
|
| 42 | |
|
|
| 43 | There are two kinds of GLEPs. A Standards Track GLEP describes a new feature |
|
|
| 44 | or implementation for Gentoo Linux. An Informational GLEP describes provides |
|
|
| 45 | general guidelines or information to the Gentoo Linux community, but does not |
|
|
| 46 | propose a new feature. Informational GLEPs do not necessarily represent a |
|
|
| 47 | Gentoo Linux community consensus or recommendation, so users and implementors |
|
|
| 48 | are free to ignore Informational GLEPs or follow their advice. |
|
|
| 49 | |
|
|
| 50 | |
|
|
| 51 | GLEP Work Flow |
|
|
| 52 | ============== |
|
|
| 53 | |
|
|
| 54 | The GLEP editors assign GLEP numbers and change their status. The current |
|
|
| 55 | GLEP editors are Grant Goodyear and hopefully somebody else. Please send all |
|
|
| 56 | GLEP-related email to <glep@gentoo.org>. |
|
|
| 57 | |
|
|
| 58 | The GLEP process begins with a new idea for Gentoo Linux. It is highly |
|
|
| 59 | recommended that a single GLEP contain a single key proposal or new idea. The |
|
|
| 60 | more focussed the GLEP, the more successful it tends to be. The GLEP editors |
|
|
| 61 | reserve the right to reject GLEP proposals if they appear too unfocussed or |
|
|
| 62 | too broad. If in doubt, split your GLEP into several well-focussed ones. |
|
|
| 63 | |
|
|
| 64 | Each GLEP must have a champion -- someone who writes the GLEP using the style |
|
|
| 65 | and format described below, shepherds the discussions in the appropriate |
|
|
| 66 | forums, and attempts to build community consensus around the idea. The GLEP |
|
|
| 67 | champion (a.k.a. Author) should first attempt to ascertain whether the idea is |
|
|
| 68 | GLEP-able. Small enhancements or patches often don't need a GLEP and can be |
|
|
| 69 | injected into the Gentoo Linux development work flow with an enhancement "bug" |
|
|
| 70 | submitted to the Gentoo Linux bugzilla [#BUGS]_. |
|
|
| 71 | |
|
|
| 72 | The GLEP champion then emails the GLEP editor <glep@gentoo.org> with a |
|
|
| 73 | proposed title and a rough, but fleshed out, draft of the GLEP. This draft |
|
|
| 74 | must be written in GLEP style as described below. |
|
|
| 75 | |
|
|
| 76 | If the GLEP editor approves, he will assign the GLEP a number, label it |
|
|
| 77 | as Standards Track (a better name would be nice here -- suggestions?) |
|
|
| 78 | or Informational, give it status "Draft", and |
|
|
| 79 | create and check-in the initial draft of the GLEP. The GLEP editors will |
|
|
| 80 | not unreasonably deny a GLEP. Reasons for denying GLEP status include |
|
|
| 81 | duplication of effort, being technically unsound, not providing proper |
|
|
| 82 | motivation or addressing backwards compatibility, or not in keeping |
|
|
| 83 | with Gentoo Linux philosophy. |
|
|
| 84 | |
|
|
| 85 | If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to the |
|
|
| 86 | gentoo-dev@gentoo.org mailing list to help flesh it out, gain feedback and |
|
|
| 87 | consensus from the community at large, and improve the GLEP for re-submission. |
|
|
| 88 | |
|
|
| 89 | The author of the GLEP is then responsible for posting the GLEP to the |
|
|
| 90 | gentoo-dev mailing list and to the Gentoo Linux forums [#FORUMS]_, and |
|
|
| 91 | marshaling community support for it. As updates are necessary, the GLEP |
|
|
| 92 | author can check in new versions if they have CVS commit permissions, or can |
|
|
| 93 | email new GLEP versions to the GLEP editors for committing. |
|
|
| 94 | |
|
|
| 95 | Standards Track GLEPs consist of two parts, a design document and a reference |
|
|
| 96 | implementation. The GLEP should be reviewed and accepted before a reference |
|
|
| 97 | implementation is begun, unless a reference implementation will aid people in |
|
|
| 98 | studying the GLEP. Standards Track GLEPs must include an implementation -- in |
|
|
| 99 | the form of code, patch, or URL to same -- before it can be considered Final. |
|
|
| 100 | |
|
|
| 101 | GLEP authors are responsible for collecting community feedback on a GLEP |
|
|
| 102 | before submitting it for review. A GLEP that has not been discussed on |
|
|
| 103 | gentoo-dev@gentoo.org and/or the Gentoo Linux forums [#FORUMS]_ will not be |
|
|
| 104 | accepted. However, wherever possible, long open-ended discussions on public |
|
|
| 105 | mailing lists should be avoided. Strategies to keep the discussions efficient |
|
|
| 106 | include setting up a specific forums thread for the topic, having the GLEP |
|
|
| 107 | author accept private comments in the early design phases, etc. GLEP authors |
|
|
| 108 | should use their discretion here. |
|
|
| 109 | |
|
|
| 110 | Once the authors have completed a GLEP, they must inform the GLEP editors that |
|
|
| 111 | it is ready for review. GLEPs are reviewed by the Gentoo Linux Chief |
|
|
| 112 | Architect or Development Manager, who may accept or reject a GLEP outright, or |
|
|
| 113 | send it back to the author(s) for revision. For a GLEP that is pre-determined |
|
|
| 114 | to be acceptable (e.g., it is an obvious win as-is and/or its implementation |
|
|
| 115 | has already been checked in) the Chief Architect or the Development Manager |
|
|
| 116 | may also initiate a GLEP review, first notifying the GLEP author(s) and giving |
|
|
| 117 | them a chance to make revisions. |
|
|
| 118 | |
|
|
| 119 | For a GLEP to be accepted it must meet certain minimum criteria. It must be a |
|
|
| 120 | clear and complete description of the proposed enhancement. The enhancement |
|
|
| 121 | must represent a net improvement. The proposed implementation, if applicable, |
|
|
| 122 | must be solid and must not complicate the distribution unduly. Finally, a |
|
|
| 123 | proposed enhancement must satisfy the philosophy of Gentoo Linux. |
|
|
| 124 | |
|
|
| 125 | Once a GLEP has been accepted, the reference implementation must be completed. |
|
|
| 126 | When the reference implementation is complete and accepted, the status will be |
|
|
| 127 | changed to "Final". |
|
|
| 128 | |
|
|
| 129 | A GLEP can also be assigned status "Deferred". The GLEP author or editor can |
|
|
| 130 | assign the GLEP this status when no progress is being made on the GLEP. Once |
|
|
| 131 | a GLEP is deferred, the GLEP editor can re-assign it to draft status. |
|
|
| 132 | |
|
|
| 133 | A GLEP can also be "Rejected". Perhaps after all is said and done it was not |
|
|
| 134 | a good idea. It is still important to have a record of this fact. |
|
|
| 135 | |
|
|
| 136 | GLEPs can also be replaced by a different GLEP, rendering the original |
|
|
| 137 | obsolete (where version 2 of a policy, for example, might replace version 1). |
|
|
| 138 | |
|
|
| 139 | GLEP work flow is as follows:: |
|
|
| 140 | |
|
|
| 141 | Draft -> Accepted -> Final -> Replaced |
|
|
| 142 | ^ |
|
|
| 143 | +----> Rejected |
|
|
| 144 | v |
|
|
| 145 | Deferred |
|
|
| 146 | |
|
|
| 147 | Some Informational GLEPs may also have a status of "Active" if they are never |
|
|
| 148 | meant to be completed. E.g. GLEP 1 (this GLEP). |
|
|
| 149 | |
|
|
| 150 | |
|
|
| 151 | What belongs in a successful GLEP? |
|
|
| 152 | ================================== |
|
|
| 153 | |
|
|
| 154 | Each GLEP should have the following parts: |
|
|
| 155 | |
|
|
| 156 | 1. Preamble -- RFC 822 style headers containing meta-data about the |
|
|
| 157 | GLEP, including the GLEP number, a short descriptive title (limited |
|
|
| 158 | to a maximum of 44 characters), the names, and optionally the |
|
|
| 159 | contact info for each author, etc. |
|
|
| 160 | |
|
|
| 161 | 2. Abstract -- a short (~200 word) description of the technical issue |
|
|
| 162 | being addressed. |
|
|
| 163 | |
|
|
| 164 | 3. Motivation -- The motivation is critical for GLEPs that want to |
|
|
| 165 | change the Gentoo Linux functionality. It should clearly explain why the |
|
|
| 166 | existing functionality or policy is inadequate to address the problem that |
|
|
| 167 | the GLEP solves. GLEP submissions without sufficient motivation may be |
|
|
| 168 | rejected outright. |
|
|
| 169 | |
|
|
| 170 | 4. Specification -- The technical specification should describe the |
|
|
| 171 | specific areas of Gentoo Linux that would be touched by this GLEP. If new |
|
|
| 172 | functionality is being introduced, what packages will that functionality |
|
|
| 173 | affect? If new policy, who will be affected? |
|
|
| 174 | |
|
|
| 175 | 5. Rationale -- The rationale fleshes out the specification by |
|
|
| 176 | describing what motivated the design and why particular design decisions |
|
|
| 177 | were made. It should describe alternate designs that were considered and |
|
|
| 178 | related work, e.g. how the feature is supported in other distributions. |
|
|
| 179 | |
|
|
| 180 | The rationale should provide evidence of consensus within the community and |
|
|
| 181 | discuss important objections or concerns raised during discussion. |
|
|
| 182 | |
|
|
| 183 | 6. Backwards Compatibility -- All GLEPs |
|
|
| 184 | must include a section describing any issues of backwards incompatibilities |
|
|
| 185 | and their severity. The GLEP must explain how the author proposes to deal |
|
|
| 186 | with these incompatibilities. (Even if there are none, this section should |
|
|
| 187 | be included to clearly state that fact.) GLEP submissions without a |
|
|
| 188 | sufficient backwards compatibility treatise may be rejected outright. |
|
|
| 189 | |
|
|
| 190 | 7. Reference Implementation -- The reference implementation must be |
|
|
| 191 | completed before any GLEP is given status "Final", but it need not be |
|
|
| 192 | completed before the GLEP is accepted. It is better to finish the |
|
|
| 193 | specification and rationale first and reach consensus on it before writing |
|
|
| 194 | code or significantly modifying ebuilds. |
|
|
| 195 | |
|
|
| 196 | 8. Copyright/public domain -- Each GLEP must either be explicitly |
|
|
| 197 | labelled as placed in the public domain (see this GLEP as an example) or |
|
|
| 198 | licensed under the Open Publication License [#OPL]. |
|
|
| 199 | |
|
|
| 200 | |
|
|
| 201 | GLEP Formating and Template |
|
|
| 202 | =========================== |
|
|
| 203 | |
|
|
| 204 | GLEPs are written in a just-barely-marked-up version of plain ASCII text |
|
|
| 205 | called ReStructuredText [#ReSTHOME]_ that is then converted to HTML using |
|
|
| 206 | Docutils [#DOCUTILS]_. Using ReStructuredText GLEPs allows for rich markup |
|
|
| 207 | that is still quite easy to read, but results in much better-looking and more |
|
|
| 208 | functional HTML. Moreover, it should be straightforward to convert GLEPs to |
|
|
| 209 | Gentoo Linux guide xml [#GUIDEXML]_ if needed. GLEP 2 contains a boilerplate |
|
|
| 210 | template [#ReST]_ for use with ReStructuredText GLEPs. |
|
|
| 211 | |
|
|
| 212 | |
|
|
| 213 | GLEP Header Preamble |
|
|
| 214 | ==================== |
|
|
| 215 | |
|
|
| 216 | Each GLEP must begin with an RFC 2822 style header preamble. The headers |
|
|
| 217 | must appear in the following order. Headers marked with "*" are |
|
|
| 218 | optional and are described below. All other headers are required. :: |
|
|
| 219 | |
|
|
| 220 | GLEP: <glep number> |
|
|
| 221 | Title: <glep title> |
|
|
| 222 | Version: <cvs version string> |
|
|
| 223 | Last-Modified: <cvs date string> |
|
|
| 224 | Author: <list of authors' real names and optionally, email addrs> |
|
|
| 225 | * Discussions-To: <email address> |
|
|
| 226 | Status: <Draft | Active | Accepted | Deferred | Rejected | |
|
|
| 227 | Final | Replaced> |
|
|
| 228 | Type: <Informational | Standards Track> |
|
|
| 229 | * Content-Type: <text/plain | text/x-rst> |
|
|
| 230 | * Requires: <glep numbers> |
|
|
| 231 | Created: <date created on, in dd-mmm-yyyy format> |
|
|
| 232 | Post-History: <dates of postings to gentoo-dev> |
|
|
| 233 | * Replaces: <glep number> |
|
|
| 234 | * Replaced-By: <glep number> |
|
|
| 235 | |
|
|
| 236 | The Author header lists the names, and optionally the email addresses |
|
|
| 237 | of all the authors/owners of the GLEP. The format of the Author header |
|
|
| 238 | value must be |
|
|
| 239 | |
|
|
| 240 | Random J. User <address@dom.ain> |
|
|
| 241 | |
|
|
| 242 | if the email address is included, and just |
|
|
| 243 | |
|
|
| 244 | Random J. User |
|
|
| 245 | |
|
|
| 246 | if the address is not given. |
|
|
| 247 | |
|
|
| 248 | If there are multiple authors, each should be on a separate line |
|
|
| 249 | following RFC 2822 continuation line conventions. Note that personal |
|
|
| 250 | email addresses in GLEPs will be obscured as a defense against spam |
|
|
| 251 | harvesters. |
|
|
| 252 | |
|
|
| 253 | While a GLEP is in private discussions (usually during the initial Draft |
|
|
| 254 | phase), a Discussions-To header will indicate the mailing list or URL where |
|
|
| 255 | the GLEP is being discussed. No Discussions-To header is necessary if the |
|
|
| 256 | GLEP is being discussed privately with the author, or on the gentoo-dev |
|
|
| 257 | mailing list. Note that email addresses in the Discussions-To header will not |
|
|
| 258 | be obscured. |
|
|
| 259 | |
|
|
| 260 | The Type header specifies the type of GLEP: Informational or Standards |
|
|
| 261 | Track. |
|
|
| 262 | |
|
|
| 263 | The format of a GLEP is specified with a Content-Type header, which for now |
|
|
| 264 | should always read "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 |
|
|
| 265 | [#ReST]_). |
|
|
| 266 | |
|
|
| 267 | The Created header records the date that the GLEP was assigned a number, while |
|
|
| 268 | Post-History is used to record the dates of when new versions of the GLEP are |
|
|
| 269 | posted to gentoo-dev. Both headers should be in dd-mmm-yyyy format, e.g. |
|
|
| 270 | 14-Aug-2001. |
|
|
| 271 | |
|
|
| 272 | GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP |
|
|
| 273 | depends on. |
|
|
| 274 | |
|
|
| 275 | GLEPs may also have a Replaced-By header indicating that a GLEP has been |
|
|
| 276 | rendered obsolete by a later document; the value is the number of the GLEP |
|
|
| 277 | that replaces the current document. The newer GLEP must have a Replaces |
|
|
| 278 | header containing the number of the GLEP that it rendered obsolete. |
|
|
| 279 | |
|
|
| 280 | |
|
|
| 281 | Reporting GLEP Bugs, or Submitting GLEP Updates |
|
|
| 282 | =============================================== |
|
|
| 283 | |
|
|
| 284 | How you report a bug, or submit a GLEP update depends on several factors, such |
|
|
| 285 | as the maturity of the GLEP, the preferences of the GLEP author, and the |
|
|
| 286 | nature of your comments. For the early draft stages of the GLEP, it's |
|
|
| 287 | probably best to send your comments and changes directly to the GLEP author. |
|
|
| 288 | For more mature, or finished GLEPs you may want to submit corrections to the |
|
|
| 289 | Gentoo Linux bugzilla [#BUGS]_ so that your changes don't get lost. If the GLEP |
|
|
| 290 | author is a Gentoo Linux developer, assign the bug/patch to him, otherwise |
|
|
| 291 | assign it to the GLEP editors. |
|
|
| 292 | |
|
|
| 293 | When in doubt about where to send your changes, please check first with the |
|
|
| 294 | GLEP author and/or GLEP editors. |
|
|
| 295 | |
|
|
| 296 | GLEP authors who are also Gentoo Linux developers can update the GLEPs |
|
|
| 297 | themselves by using "cvs commit" to commit their changes. |
|
|
| 298 | |
|
|
| 299 | Transferring GLEP Ownership |
|
|
| 300 | =========================== |
|
|
| 301 | |
|
|
| 302 | It occasionally becomes necessary to transfer ownership of GLEPs to a new |
|
|
| 303 | champion. In general, we'd like to retain the original author as a co-author |
|
|
| 304 | of the transferred GLEP, but that's really up to the original author. A good |
|
|
| 305 | reason to transfer ownership is because the original author no longer has the |
|
|
| 306 | time or interest in updating it or following through with the GLEP process, or |
|
|
| 307 | has fallen off the face of the 'net (i.e. is unreachable or not responding to |
|
|
| 308 | email). A bad reason to transfer ownership is because you don't agree with |
|
|
| 309 | the direction of the GLEP. We try to build consensus around a GLEP, but if |
|
|
| 310 | that's not possible, you can always submit a competing GLEP. |
|
|
| 311 | |
|
|
| 312 | If you are interested in assuming ownership of a GLEP, send a message asking |
|
|
| 313 | to take over, addressed to both the original author and the GLEP editors |
|
|
| 314 | <glep@gentoo.org>. If the original author doesn't respond to email in a |
|
|
| 315 | timely manner, the GLEP editors will make a unilateral decision (it's not like |
|
|
| 316 | such decisions can't be reversed :). |
|
|
| 317 | |
|
|
| 318 | |
|
|
| 319 | References and Footnotes |
|
|
| 320 | ======================== |
|
|
| 321 | |
|
|
| 322 | .. [#PYTHON] http://www.python.org |
|
|
| 323 | |
|
|
| 324 | .. [#PEPS] http://www.python.org/peps |
|
|
| 325 | |
|
|
| 326 | .. [#PEP1] http://www.python.org/peps/pep-0001.html |
|
|
| 327 | |
|
|
| 328 | .. [#CVS] This historical record is available by the normal CVS commands |
|
|
| 329 | for retrieving older revisions. For those without direct access to the CVS |
|
|
| 330 | tree, you can browse the current and past GLEP revisions via the Gentoo |
|
|
| 331 | Linux viewcvs web site at |
|
|
| 332 | http://cvs.gentoo.org/cgi-bin/viewcvs.cgi/gentoo/xml/htdocs/proj/en/glep/ |
|
|
| 333 | |
|
|
| 334 | .. [#ReST] GLEP 2, Sample ReStructuredText GLEP Template, |
|
|
| 335 | (http://glep.gentoo.org/glep-0002.html) |
|
|
| 336 | |
|
|
| 337 | .. [#BUGS] http://bugs.gentoo.org |
|
|
| 338 | |
|
|
| 339 | .. [#FORUMS] http://forums.gentoo.org |
|
|
| 340 | |
|
|
| 341 | .. [#OPL] http://www.opencontent.org/openpub/ |
|
|
| 342 | |
|
|
| 343 | .. [#ReSTHOME] http://docutils.sourceforge.net/rst.html |
|
|
| 344 | |
|
|
| 345 | .. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml |
|
|
| 346 | |
|
|
| 347 | .. [#DOCUTILS] http://docutils.sourceforge.net/ |
|
|
| 348 | |
|
|
| 349 | |
|
|
| 350 | Copyright |
|
|
| 351 | ========= |
|
|
| 352 | |
|
|
| 353 | This document has been placed in the public domain. |
|
|
Parent Directory
| 
Revision Log
| 
Patch