1 |
GLEP: 1 |
2 |
Title: GLEP Purpose and Guidelines |
3 |
Version: $Revision: 1.1 $ |
4 |
Last-Modified: $Date: 2003/06/02 17:03:08 $ |
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. |