1 |
peper |
1.10 |
GLEP: 1 |
2 |
|
|
Title: GLEP Purpose and Guidelines |
3 |
dev-zero |
1.12 |
Version: $Revision: 1.11 $ |
4 |
|
|
Last-Modified: $Date: 2008/01/20 02:56:39 $ |
5 |
peper |
1.10 |
Author: Grant Goodyear <g2boojum@gentoo.org> |
6 |
|
|
Status: Active |
7 |
|
|
Type: Informational |
8 |
|
|
Content-Type: text/x-rst |
9 |
|
|
Created: 31-May-2003 |
10 |
dev-zero |
1.12 |
Post-History: 1-Jun-2003, 2-Jul-2003, 19-Jan-2008, 05-Jun-2008 |
11 |
peper |
1.10 |
|
12 |
|
|
Credits |
13 |
|
|
======= |
14 |
|
|
|
15 |
|
|
The GLEP concept, and, in fact, much of the text of this document, |
16 |
|
|
is liberally stolen from Python's [#Python]_ PEPs |
17 |
|
|
[#PEPS]_, especially |
18 |
|
|
PEP-0001 [#PEP1]_ by Barry A. Warsaw, Jeremy Hylton, and David Goodger. |
19 |
|
|
|
20 |
|
|
What is a GLEP? |
21 |
|
|
=============== |
22 |
|
|
|
23 |
|
|
GLEP stands for "Gentoo Linux Enhancement Proposal". A GLEP is a design |
24 |
|
|
document providing information to the Gentoo Linux community, or describing |
25 |
|
|
a new feature for Gentoo Linux. The GLEP should provide a concise technical |
26 |
|
|
specification of the feature and rationale for the feature. |
27 |
|
|
|
28 |
|
|
We intend GLEPs to be the primary mechanisms for proposing *significant* new |
29 |
|
|
features, for collecting community input on an issue, and for |
30 |
|
|
documenting the design decisions that have gone into Gentoo Linux. The GLEP |
31 |
|
|
author is responsible for building consensus within the community and |
32 |
|
|
documenting dissenting opinions. |
33 |
|
|
|
34 |
|
|
Because the GLEPs are maintained as text files under CVS control, their |
35 |
|
|
revision history is the historical record of the feature proposal |
36 |
|
|
[#CVS]_. |
37 |
|
|
|
38 |
|
|
|
39 |
|
|
Kinds of GLEPs |
40 |
|
|
============== |
41 |
|
|
|
42 |
|
|
There are two kinds of GLEPs. A Standards Track GLEP describes a new feature |
43 |
|
|
or implementation for Gentoo Linux. An Informational GLEP describes provides |
44 |
|
|
general guidelines or information to the Gentoo Linux community, but does not |
45 |
|
|
propose a new feature. Informational GLEPs do not necessarily represent a |
46 |
|
|
Gentoo Linux community consensus or recommendation, so users and implementors |
47 |
|
|
are free to ignore Informational GLEPs or follow their advice. |
48 |
|
|
|
49 |
|
|
|
50 |
|
|
GLEP Work Flow |
51 |
|
|
============== |
52 |
|
|
|
53 |
|
|
The GLEP editors assign GLEP numbers and change their status. The current |
54 |
|
|
GLEP editors are Grant Goodyear and Alastair Tse. Please send all |
55 |
|
|
GLEP-related email to <glep@gentoo.org>. |
56 |
|
|
|
57 |
|
|
The GLEP process begins with a new idea for Gentoo Linux. It is highly |
58 |
|
|
recommended that a single GLEP contain a single key proposal or new idea. The |
59 |
|
|
more focussed the GLEP, the more successful it tends to be. The GLEP editors |
60 |
|
|
reserve the right to reject GLEP proposals if they appear too unfocussed or |
61 |
|
|
too broad. If in doubt, split your GLEP into several well-focussed ones. |
62 |
|
|
|
63 |
|
|
Each GLEP must have a champion -- someone who writes the GLEP using the style |
64 |
|
|
and format described below, shepherds the discussions in the appropriate |
65 |
|
|
forums, and attempts to build community consensus around the idea. The GLEP |
66 |
|
|
champion (a.k.a. Author) should first attempt to ascertain whether the idea is |
67 |
|
|
GLEP-able. Small enhancements or patches often don't need a GLEP and can be |
68 |
|
|
injected into the Gentoo Linux development work flow with an enhancement "bug" |
69 |
|
|
submitted to the Gentoo Linux bugzilla [#BUGS]_. |
70 |
|
|
|
71 |
|
|
The GLEP champion then emails the GLEP editors <glep@gentoo.org> with a |
72 |
|
|
proposed title and a rough, but fleshed out, draft of the GLEP. This draft |
73 |
|
|
must be written in GLEP style as described below. |
74 |
|
|
|
75 |
|
|
If the GLEP editor accepts the GLEP, he will assign the GLEP a number, label |
76 |
|
|
it as Standards Track (a better name would be nice here -- suggestions?) or |
77 |
|
|
Informational, give it status "Draft", and create and check-in the initial |
78 |
|
|
draft of the GLEP. The GLEP editors will not unreasonably deny a GLEP. |
79 |
|
|
Reasons for denying GLEP status include duplication of effort, being |
80 |
|
|
technically unsound, not providing proper motivation or addressing backwards |
81 |
|
|
compatibility, or not in keeping with Gentoo Linux philosophy. |
82 |
|
|
|
83 |
|
|
If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to the |
84 |
|
|
gentoo-dev@gentoo.org mailing list to help flesh it out, gain feedback and |
85 |
|
|
consensus from the community at large, and improve the GLEP for re-submission. |
86 |
|
|
|
87 |
|
|
The author of the GLEP is then responsible for posting the GLEP to the |
88 |
|
|
gentoo-dev mailing list and to the Gentoo Linux forums [#FORUMS]_, and |
89 |
|
|
marshaling community support for it. As updates are necessary, the GLEP |
90 |
|
|
author can check in new versions if they have CVS commit permissions, or can |
91 |
|
|
email new GLEP versions to the GLEP editors for committing. |
92 |
|
|
|
93 |
|
|
Standards Track GLEPs consist of two parts, a design document and a reference |
94 |
|
|
implementation. The GLEP should be reviewed and accepted before a reference |
95 |
|
|
implementation is begun, unless a reference implementation will aid people in |
96 |
|
|
studying the GLEP. Standards Track GLEPs must include an implementation -- in |
97 |
|
|
the form of code, patch, or URL to same -- before it can be considered Final. |
98 |
|
|
|
99 |
|
|
GLEP authors are responsible for collecting community feedback on a GLEP |
100 |
|
|
before submitting it for review. A GLEP that has not been discussed on |
101 |
|
|
gentoo-dev@gentoo.org and/or the Gentoo Linux forums [#FORUMS]_ will not be |
102 |
|
|
accepted. However, wherever possible, long open-ended discussions on public |
103 |
|
|
mailing lists should be avoided. Strategies to keep the discussions efficient |
104 |
|
|
include setting up a specific forums thread for the topic, having the GLEP |
105 |
|
|
author accept private comments in the early design phases, etc. GLEP authors |
106 |
|
|
should use their discretion here. |
107 |
|
|
|
108 |
|
|
Once the authors have completed a GLEP, they must inform the GLEP editors that |
109 |
|
|
it is ready for review. GLEPs are reviewed by the appropriate Gentoo |
110 |
|
|
Manager [#MANAGER]_, who may approve or reject a GLEP outright, or |
111 |
|
|
send it back to the author(s) for revision. For a GLEP that is pre-determined |
112 |
|
|
to be approvable (e.g., it is an obvious win as-is and/or its implementation |
113 |
|
|
has already been checked in) the appropriate Gentoo Manager [#MANAGER]_ |
114 |
|
|
may also initiate a GLEP review, first notifying the GLEP author(s) and giving |
115 |
|
|
them a chance to make revisions. |
116 |
|
|
|
117 |
|
|
For a GLEP to be approved it must meet certain minimum criteria. It must be a |
118 |
|
|
clear and complete description of the proposed enhancement. The enhancement |
119 |
|
|
must represent a net improvement. The proposed implementation, if applicable, |
120 |
|
|
must be solid and must not complicate the distribution unduly. Finally, a |
121 |
|
|
proposed enhancement must satisfy the philosophy of Gentoo Linux. |
122 |
|
|
|
123 |
|
|
Once a GLEP has been accepted, the reference implementation must be completed. |
124 |
|
|
When the reference implementation is complete and accepted, the status will be |
125 |
|
|
changed to "Final". |
126 |
|
|
|
127 |
|
|
A GLEP can also be assigned status "Deferred". The GLEP author or editor can |
128 |
|
|
assign the GLEP this status when no progress is being made on the GLEP. Once |
129 |
|
|
a GLEP is deferred, the GLEP editor can re-assign it to draft status. |
130 |
|
|
|
131 |
|
|
A GLEP can also be "Rejected". Perhaps after all is said and done it was not |
132 |
|
|
a good idea. It is still important to have a record of this fact. |
133 |
|
|
|
134 |
|
|
GLEPs can also be replaced by a different GLEP, rendering the original |
135 |
|
|
obsolete (where version 2 of a policy, for example, might replace version 1). |
136 |
|
|
|
137 |
|
|
GLEP work flow is as follows:: |
138 |
|
|
|
139 |
|
|
Draft -> Accepted -> Final -> Replaced |
140 |
|
|
^ |
141 |
|
|
+----> Rejected |
142 |
|
|
v |
143 |
|
|
Deferred |
144 |
|
|
|
145 |
|
|
Some Informational GLEPs may also have a status of "Active" if they are never |
146 |
|
|
meant to be completed. E.g. GLEP 1 (this GLEP). |
147 |
|
|
|
148 |
|
|
|
149 |
|
|
What belongs in a successful GLEP? |
150 |
|
|
================================== |
151 |
|
|
|
152 |
|
|
Each GLEP should have the following parts: |
153 |
|
|
|
154 |
|
|
1. Preamble -- RFC 822 style headers containing meta-data about the |
155 |
|
|
GLEP, including the GLEP number, a short descriptive title (limited |
156 |
|
|
to a maximum of 44 characters), the names, and optionally the |
157 |
|
|
contact info for each author, etc. |
158 |
|
|
|
159 |
|
|
2. Abstract -- a short (~200 word) description of the technical issue |
160 |
|
|
being addressed. |
161 |
|
|
|
162 |
|
|
3. Motivation -- The motivation is critical for GLEPs that want to |
163 |
|
|
modify Gentoo Linux functionality. It should clearly explain why the |
164 |
|
|
existing functionality or policy is inadequate to address the problem that |
165 |
|
|
the GLEP solves. GLEP submissions without sufficient motivation may be |
166 |
|
|
rejected outright. |
167 |
|
|
|
168 |
|
|
4. Specification -- The technical specification should describe the |
169 |
|
|
specific areas of Gentoo Linux that would be touched by this GLEP. If new |
170 |
|
|
functionality is being introduced, what packages will that functionality |
171 |
|
|
affect? If new policy, who will be affected? |
172 |
|
|
|
173 |
|
|
5. Rationale -- The rationale fleshes out the specification by |
174 |
|
|
describing what motivated the design and why particular design decisions |
175 |
|
|
were made. It should describe alternate designs that were considered and |
176 |
|
|
related work, e.g. how the feature is supported in other distributions. |
177 |
|
|
|
178 |
|
|
The rationale should provide evidence of consensus within the community and |
179 |
|
|
discuss important objections or concerns raised during discussion. |
180 |
|
|
|
181 |
|
|
6. Backwards Compatibility -- All GLEPs |
182 |
|
|
must include a section describing any issues of backwards incompatibilities |
183 |
|
|
and their severity. The GLEP must explain how the author proposes to deal |
184 |
|
|
with these incompatibilities. (Even if there are none, this section should |
185 |
|
|
be included to clearly state that fact.) GLEP submissions without a |
186 |
|
|
sufficient backwards compatibility treatise may be rejected outright. |
187 |
|
|
|
188 |
|
|
7. Reference Implementation -- The reference implementation must be |
189 |
|
|
completed before any GLEP is given status "Final", but it need not be |
190 |
|
|
completed before the GLEP is accepted. It is better to finish the |
191 |
|
|
specification and rationale first and reach consensus on it before writing |
192 |
|
|
code or significantly modifying ebuilds. |
193 |
|
|
|
194 |
|
|
8. Copyright/public domain -- Each GLEP must either be explicitly |
195 |
|
|
labelled as placed in the public domain (see this GLEP as an example) or |
196 |
|
|
licensed under the Open Publication License [#OPL]. |
197 |
|
|
|
198 |
|
|
|
199 |
|
|
GLEP Formating and Template |
200 |
|
|
=========================== |
201 |
|
|
|
202 |
|
|
GLEPs are written either in Gentoo Linux Guide-XML [#GUIDEXML]_ or in |
203 |
|
|
a just-barely-marked-up version of plain ASCII text |
204 |
|
|
called ReStructuredText [#ReSTHOME]_ that is then converted to HTML using |
205 |
|
|
Docutils [#DOCUTILS]_. Using ReStructuredText GLEPs allows for rich markup |
206 |
|
|
that is still quite easy to read, but results in much better-looking and more |
207 |
|
|
functional HTML. Moreover, it should be straightforward to convert GLEPs to |
208 |
|
|
Gentoo Linux guide xml [#GUIDEXML]_ if needed. GLEP 2 contains a boilerplate |
209 |
|
|
template [#ReST]_ for use with ReStructuredText GLEPs. |
210 |
|
|
|
211 |
|
|
|
212 |
|
|
GLEP Header Preamble |
213 |
|
|
==================== |
214 |
|
|
|
215 |
|
|
Each GLEP must begin with an RFC 2822 style header preamble. The headers |
216 |
|
|
must appear in the following order. Headers marked with "*" are |
217 |
|
|
optional and are described below. All other headers are required. :: |
218 |
|
|
|
219 |
|
|
GLEP: <glep number> |
220 |
|
|
Title: <glep title> |
221 |
|
|
Version: <cvs version string> |
222 |
|
|
Last-Modified: <cvs date string> |
223 |
|
|
Author: <list of authors' real names and optionally, email addrs> |
224 |
|
|
* Discussions-To: <email address> |
225 |
|
|
Status: <Draft | Active | Accepted | Deferred | Rejected | |
226 |
|
|
Final | Replaced> |
227 |
|
|
Type: <Informational | Standards Track> |
228 |
|
|
* Content-Type: <text/plain | text/x-rst> |
229 |
|
|
* Requires: <glep numbers> |
230 |
|
|
Created: <date created on, in dd-mmm-yyyy format> |
231 |
|
|
Post-History: <dates of postings to gentoo-dev> |
232 |
|
|
* Replaces: <glep number> |
233 |
|
|
* Replaced-By: <glep number> |
234 |
|
|
|
235 |
|
|
The Author header lists the names, and optionally the email addresses |
236 |
|
|
of all the authors/owners of the GLEP. The format of the Author header |
237 |
|
|
value must be |
238 |
|
|
|
239 |
|
|
Random J. User <address@dom.ain> |
240 |
|
|
|
241 |
|
|
if the email address is included, and just |
242 |
|
|
|
243 |
|
|
Random J. User |
244 |
|
|
|
245 |
|
|
if the address is not given. |
246 |
|
|
|
247 |
|
|
If there are multiple authors, each should be on a separate line |
248 |
|
|
following RFC 2822 continuation line conventions. Note that personal |
249 |
|
|
email addresses in GLEPs will be obscured as a defense against spam |
250 |
|
|
harvesters. |
251 |
|
|
|
252 |
|
|
While a GLEP is in private discussions (usually during the initial Draft |
253 |
|
|
phase), a Discussions-To header will indicate the mailing list or URL where |
254 |
|
|
the GLEP is being discussed. No Discussions-To header is necessary if the |
255 |
|
|
GLEP is being discussed privately with the author, or on the gentoo-dev |
256 |
|
|
mailing list. Note that email addresses in the Discussions-To header will not |
257 |
|
|
be obscured. |
258 |
|
|
|
259 |
|
|
The Type header specifies the type of GLEP: Informational or Standards |
260 |
|
|
Track. |
261 |
|
|
|
262 |
|
|
The format of a GLEP is specified with a Content-Type header, which |
263 |
|
|
should read "text/xml" for Gentoo Guide XML or |
264 |
|
|
"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://www.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 |
|
|
.. [#MANAGER] http://www.gentoo.org/doc/en/management-structure.xml |
342 |
|
|
|
343 |
|
|
.. [#OPL] http://www.opencontent.org/openpub/ |
344 |
|
|
|
345 |
|
|
.. [#ReSTHOME] http://docutils.sourceforge.net/rst.html |
346 |
|
|
|
347 |
|
|
.. [#GUIDEXML] http://www.gentoo.org/doc/en/xml-guide.xml |
348 |
|
|
|
349 |
|
|
.. [#DOCUTILS] http://docutils.sourceforge.net/ |
350 |
|
|
|
351 |
|
|
|
352 |
|
|
Copyright |
353 |
|
|
========= |
354 |
|
|
|
355 |
|
|
This document has been placed in the public domain. |