|
|
1 | GLEP: 1 |
|
|
2 | Title: GLEP Purpose and Guidelines |
|
|
3 | Version: $Revision: 1.10 $ |
|
|
4 | Last-Modified: $Date: 2008/01/05 03:05:07 $ |
|
|
5 | Author: Grant Goodyear <g2boojum@gentoo.org> |
|
|
6 | Status: Active |
|
|
7 | Type: Informational |
|
|
8 | Content-Type: text/x-rst |
|
|
9 | Created: 31-May-2003 |
|
|
10 | Post-History: 1-Jun-2003, 2-Jul-2003 |
|
|
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 Alastair Tse. 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 editors <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 accepts the GLEP, he will assign the GLEP a number, label |
|
|
77 | it as Standards Track (a better name would be nice here -- suggestions?) or |
|
|
78 | Informational, give it status "Draft", and create and check-in the initial |
|
|
79 | draft of the GLEP. The GLEP editors will not unreasonably deny a GLEP. |
|
|
80 | Reasons for denying GLEP status include duplication of effort, being |
|
|
81 | technically unsound, not providing proper motivation or addressing backwards |
|
|
82 | compatibility, or not in keeping with Gentoo Linux philosophy. |
|
|
83 | |
|
|
84 | If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to the |
|
|
85 | gentoo-dev@gentoo.org mailing list to help flesh it out, gain feedback and |
|
|
86 | consensus from the community at large, and improve the GLEP for re-submission. |
|
|
87 | |
|
|
88 | The author of the GLEP is then responsible for posting the GLEP to the |
|
|
89 | gentoo-dev mailing list and to the Gentoo Linux forums [#FORUMS]_, and |
|
|
90 | marshaling community support for it. As updates are necessary, the GLEP |
|
|
91 | author can check in new versions if they have CVS commit permissions, or can |
|
|
92 | email new GLEP versions to the GLEP editors for committing. |
|
|
93 | |
|
|
94 | Standards Track GLEPs consist of two parts, a design document and a reference |
|
|
95 | implementation. The GLEP should be reviewed and accepted before a reference |
|
|
96 | implementation is begun, unless a reference implementation will aid people in |
|
|
97 | studying the GLEP. Standards Track GLEPs must include an implementation -- in |
|
|
98 | the form of code, patch, or URL to same -- before it can be considered Final. |
|
|
99 | |
|
|
100 | GLEP authors are responsible for collecting community feedback on a GLEP |
|
|
101 | before submitting it for review. A GLEP that has not been discussed on |
|
|
102 | gentoo-dev@gentoo.org and/or the Gentoo Linux forums [#FORUMS]_ will not be |
|
|
103 | accepted. However, wherever possible, long open-ended discussions on public |
|
|
104 | mailing lists should be avoided. Strategies to keep the discussions efficient |
|
|
105 | include setting up a specific forums thread for the topic, having the GLEP |
|
|
106 | author accept private comments in the early design phases, etc. GLEP authors |
|
|
107 | should use their discretion here. |
|
|
108 | |
|
|
109 | Once the authors have completed a GLEP, they must inform the GLEP editors that |
|
|
110 | it is ready for review. GLEPs are reviewed by the appropriate Gentoo |
|
|
111 | Manager [#MANAGER]_, who may approve or reject a GLEP outright, or |
|
|
112 | send it back to the author(s) for revision. For a GLEP that is pre-determined |
|
|
113 | to be approvable (e.g., it is an obvious win as-is and/or its implementation |
|
|
114 | has already been checked in) the appropriate Gentoo Manager [#MANAGER]_ |
|
|
115 | may also initiate a GLEP review, first notifying the GLEP author(s) and giving |
|
|
116 | them a chance to make revisions. |
|
|
117 | |
|
|
118 | For a GLEP to be approved it must meet certain minimum criteria. It must be a |
|
|
119 | clear and complete description of the proposed enhancement. The enhancement |
|
|
120 | must represent a net improvement. The proposed implementation, if applicable, |
|
|
121 | must be solid and must not complicate the distribution unduly. Finally, a |
|
|
122 | proposed enhancement must satisfy the philosophy of Gentoo Linux. |
|
|
123 | |
|
|
124 | Once a GLEP has been accepted, the reference implementation must be completed. |
|
|
125 | When the reference implementation is complete and accepted, the status will be |
|
|
126 | changed to "Final". |
|
|
127 | |
|
|
128 | A GLEP can also be assigned status "Deferred". The GLEP author or editor can |
|
|
129 | assign the GLEP this status when no progress is being made on the GLEP. Once |
|
|
130 | a GLEP is deferred, the GLEP editor can re-assign it to draft status. |
|
|
131 | |
|
|
132 | A GLEP can also be "Rejected". Perhaps after all is said and done it was not |
|
|
133 | a good idea. It is still important to have a record of this fact. |
|
|
134 | |
|
|
135 | GLEPs can also be replaced by a different GLEP, rendering the original |
|
|
136 | obsolete (where version 2 of a policy, for example, might replace version 1). |
|
|
137 | |
|
|
138 | GLEP work flow is as follows:: |
|
|
139 | |
|
|
140 | Draft -> Accepted -> Final -> Replaced |
|
|
141 | ^ |
|
|
142 | +----> Rejected |
|
|
143 | v |
|
|
144 | Deferred |
|
|
145 | |
|
|
146 | Some Informational GLEPs may also have a status of "Active" if they are never |
|
|
147 | meant to be completed. E.g. GLEP 1 (this GLEP). |
|
|
148 | |
|
|
149 | |
|
|
150 | What belongs in a successful GLEP? |
|
|
151 | ================================== |
|
|
152 | |
|
|
153 | Each GLEP should have the following parts: |
|
|
154 | |
|
|
155 | 1. Preamble -- RFC 822 style headers containing meta-data about the |
|
|
156 | GLEP, including the GLEP number, a short descriptive title (limited |
|
|
157 | to a maximum of 44 characters), the names, and optionally the |
|
|
158 | contact info for each author, etc. |
|
|
159 | |
|
|
160 | 2. Abstract -- a short (~200 word) description of the technical issue |
|
|
161 | being addressed. |
|
|
162 | |
|
|
163 | 3. Motivation -- The motivation is critical for GLEPs that want to |
|
|
164 | modify Gentoo Linux functionality. It should clearly explain why the |
|
|
165 | existing functionality or policy is inadequate to address the problem that |
|
|
166 | the GLEP solves. GLEP submissions without sufficient motivation may be |
|
|
167 | rejected outright. |
|
|
168 | |
|
|
169 | 4. Specification -- The technical specification should describe the |
|
|
170 | specific areas of Gentoo Linux that would be touched by this GLEP. If new |
|
|
171 | functionality is being introduced, what packages will that functionality |
|
|
172 | affect? If new policy, who will be affected? |
|
|
173 | |
|
|
174 | 5. Rationale -- The rationale fleshes out the specification by |
|
|
175 | describing what motivated the design and why particular design decisions |
|
|
176 | were made. It should describe alternate designs that were considered and |
|
|
177 | related work, e.g. how the feature is supported in other distributions. |
|
|
178 | |
|
|
179 | The rationale should provide evidence of consensus within the community and |
|
|
180 | discuss important objections or concerns raised during discussion. |
|
|
181 | |
|
|
182 | 6. Backwards Compatibility -- All GLEPs |
|
|
183 | must include a section describing any issues of backwards incompatibilities |
|
|
184 | and their severity. The GLEP must explain how the author proposes to deal |
|
|
185 | with these incompatibilities. (Even if there are none, this section should |
|
|
186 | be included to clearly state that fact.) GLEP submissions without a |
|
|
187 | sufficient backwards compatibility treatise may be rejected outright. |
|
|
188 | |
|
|
189 | 7. Reference Implementation -- The reference implementation must be |
|
|
190 | completed before any GLEP is given status "Final", but it need not be |
|
|
191 | completed before the GLEP is accepted. It is better to finish the |
|
|
192 | specification and rationale first and reach consensus on it before writing |
|
|
193 | code or significantly modifying ebuilds. |
|
|
194 | |
|
|
195 | 8. Copyright/public domain -- Each GLEP must either be explicitly |
|
|
196 | labelled as placed in the public domain (see this GLEP as an example) or |
|
|
197 | licensed under the Open Publication License [#OPL]. |
|
|
198 | |
|
|
199 | |
|
|
200 | GLEP Formating and Template |
|
|
201 | =========================== |
|
|
202 | |
|
|
203 | GLEPs are written either in Gentoo Linux Guide-XML [#GUIDEXML]_ or in |
|
|
204 | 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 |
|
|
264 | should read "text/xml" for Gentoo Guide XML or |
|
|
265 | "text/x-rst" for ReStructuredText GLEPs (see GLEP 2 |
|
|
266 | [#ReST]_). |
|
|
267 | |
|
|
268 | The Created header records the date that the GLEP was assigned a number, while |
|
|
269 | Post-History is used to record the dates of when new versions of the GLEP are |
|
|
270 | posted to gentoo-dev. Both headers should be in dd-mmm-yyyy format, e.g. |
|
|
271 | 14-Aug-2001. |
|
|
272 | |
|
|
273 | GLEPs may have a Requires header, indicating the GLEP numbers that this GLEP |
|
|
274 | depends on. |
|
|
275 | |
|
|
276 | GLEPs may also have a Replaced-By header indicating that a GLEP has been |
|
|
277 | rendered obsolete by a later document; the value is the number of the GLEP |
|
|
278 | that replaces the current document. The newer GLEP must have a Replaces |
|
|
279 | header containing the number of the GLEP that it rendered obsolete. |
|
|
280 | |
|
|
281 | |
|
|
282 | Reporting GLEP Bugs, or Submitting GLEP Updates |
|
|
283 | =============================================== |
|
|
284 | |
|
|
285 | How you report a bug, or submit a GLEP update depends on several factors, such |
|
|
286 | as the maturity of the GLEP, the preferences of the GLEP author, and the |
|
|
287 | nature of your comments. For the early draft stages of the GLEP, it's |
|
|
288 | probably best to send your comments and changes directly to the GLEP author. |
|
|
289 | For more mature, or finished GLEPs you may want to submit corrections to the |
|
|
290 | Gentoo Linux bugzilla [#BUGS]_ so that your changes don't get lost. If the GLEP |
|
|
291 | author is a Gentoo Linux developer, assign the bug/patch to him, otherwise |
|
|
292 | assign it to the GLEP editors. |
|
|
293 | |
|
|
294 | When in doubt about where to send your changes, please check first with the |
|
|
295 | GLEP author and/or GLEP editors. |
|
|
296 | |
|
|
297 | GLEP authors who are also Gentoo Linux developers can update the GLEPs |
|
|
298 | themselves by using "cvs commit" to commit their changes. |
|
|
299 | |
|
|
300 | Transferring GLEP Ownership |
|
|
301 | =========================== |
|
|
302 | |
|
|
303 | It occasionally becomes necessary to transfer ownership of GLEPs to a new |
|
|
304 | champion. In general, we'd like to retain the original author as a co-author |
|
|
305 | of the transferred GLEP, but that's really up to the original author. A good |
|
|
306 | reason to transfer ownership is because the original author no longer has the |
|
|
307 | time or interest in updating it or following through with the GLEP process, or |
|
|
308 | has fallen off the face of the 'net (i.e. is unreachable or not responding to |
|
|
309 | email). A bad reason to transfer ownership is because you don't agree with |
|
|
310 | the direction of the GLEP. We try to build consensus around a GLEP, but if |
|
|
311 | that's not possible, you can always submit a competing GLEP. |
|
|
312 | |
|
|
313 | If you are interested in assuming ownership of a GLEP, send a message asking |
|
|
314 | to take over, addressed to both the original author and the GLEP editors |
|
|
315 | <glep@gentoo.org>. If the original author doesn't respond to email in a |
|
|
316 | timely manner, the GLEP editors will make a unilateral decision (it's not like |
|
|
317 | such decisions can't be reversed :). |
|
|
318 | |
|
|
319 | |
|
|
320 | References and Footnotes |
|
|
321 | ======================== |
|
|
322 | |
|
|
323 | .. [#PYTHON] http://www.python.org |
|
|
324 | |
|
|
325 | .. [#PEPS] http://www.python.org/peps |
|
|
326 | |
|
|
327 | .. [#PEP1] http://www.python.org/peps/pep-0001.html |
|
|
328 | |
|
|
329 | .. [#CVS] This historical record is available by the normal CVS commands |
|
|
330 | for retrieving older revisions. For those without direct access to the CVS |
|
|
331 | tree, you can browse the current and past GLEP revisions via the Gentoo |
|
|
332 | Linux viewcvs web site at |
|
|
333 | http://www.gentoo.org/cgi-bin/viewcvs.cgi/gentoo/xml/htdocs/proj/en/glep/ |
|
|
334 | |
|
|
335 | .. [#ReST] GLEP 2, Sample ReStructuredText GLEP Template, |
|
|
336 | (http://glep.gentoo.org/glep-0002.html) |
|
|
337 | |
|
|
338 | .. [#BUGS] http://bugs.gentoo.org |
|
|
339 | |
|
|
340 | .. [#FORUMS] http://forums.gentoo.org |
|
|
341 | |
|
|
342 | .. [#MANAGER] http://www.gentoo.org/doc/en/management-structure.xml |
|
|
343 | |
|
|
344 | .. [#OPL] http://www.opencontent.org/openpub/ |
|
|
345 | |
|
|
346 | .. [#ReSTHOME] http://docutils.sourceforge.net/rst.html |
|
|
347 | |
|
|
348 | .. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml |
|
|
349 | |
|
|
350 | .. [#DOCUTILS] http://docutils.sourceforge.net/ |
|
|
351 | |
|
|
352 | |
|
|
353 | Copyright |
|
|
354 | ========= |
|
|
355 | |
|
|
356 | This document has been placed in the public domain. |
Parent Directory
| 
Revision Log
| 
Patch