diff options
Diffstat (limited to 'glep-1.txt')
| -rw-r--r-- | glep-1.txt | 410 |
1 files changed, 410 insertions, 0 deletions
diff --git a/glep-1.txt b/glep-1.txt new file mode 100644 index 0000000..80bffd0 --- /dev/null +++ b/glep-1.txt @@ -0,0 +1,410 @@ +GLEP: 1 +Title: GLEP Purpose and Guidelines +Version: $Revision: 1.1 $ +Last-Modified: $Date: 2003/05/31 15:18:03 $ +Author: Grant Goodyear +Status: Draft +Type: Informational +Content-Type: text/x-rst +Created: 31 May 2003 +Post-History: + + +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 +specification of the feature and rationale for the feature. + +We intend GLEPs to be the primary mechanisms for proposing new +features, for collecting community input on an issue, and for +documenting the design decisions that have gone into Python. The GLEP +author is responsible for building consensus within the community and +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]_. + + +Kinds of GLEPs +============= + +There are two kinds of GLEPs. A Standards Track GLEP describes a new +feature or implementation for Python. An Informational GLEP describes +a Python design issue, or provides general guidelines or information +to the Python community, but does not propose a new feature. +Informational GLEPs do not necessarily represent a Python 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 David Goodger and Barry Warsaw. Please send +all GLEP-related email to <peps@python.org>. + +The GLEP process begins with a new idea for Python. 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 Python development +work flow with a patch submission to the SourceForge `patch manager`_ +or `feature request tracker`_. + +The GLEP champion then emails the GLEP editor <peps@python.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. + +If the GLEP editor approves, he will assign the GLEP a number, label it +as Standards Track or Informational, give it status "Draft", and +create and check-in the initial draft of the GLEP. The GLEP editor will +not unreasonably deny a GLEP. Reasons for denying GLEP status include +duplication of effort, being technically unsound, not providing proper +motivation or addressing backwards compatibility, or not in keeping +with the Python philosophy. The BDFL (Benevolent Dictator for Life, +Guido van Rossum) can be consulted during the approval phase, and is +the final arbitrator of the draft's GLEP-ability. + +If a pre-GLEP is rejected, the author may elect to take the pre-GLEP to +the comp.lang.python newsgroup (a.k.a. python-list@python.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 +community 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 +editor for committing. + +Standards Track GLEPs consists 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 +python-list@python.org and/or python-dev@python.org 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 separate SIG mailing list +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 editor +that it is ready for review. GLEPs are reviewed by the BDFL and his +chosen consultants, who may accept or reject a GLEP 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 BDFL 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 interpreter unduly. Finally, a proposed enhancement must be +"pythonic" in order to be accepted by the BDFL. (However, "pythonic" +is an imprecise term; it may be defined as whatever is acceptable to +the BDFL. This logic is intentionally circular.) See GLEP 2 [2]_ for +standard library module acceptance criteria. + +Once a GLEP has been accepted, the reference implementation must be +completed. When the reference implementation is complete and accepted +by the BDFL, 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 +an API can replace version 1. + +GLEP work flow is as follows:: + + Draft -> Accepted -> Final -> Replaced + ^ + +----> Rejected + 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). + + +What belongs in a successful GLEP? +================================= + +Each GLEP should have the following parts: + +1. Preamble -- RFC 822 style headers containing meta-data about the + GLEP, including the GLEP number, a short descriptive title (limited + to a maximum of 44 characters), the names, and optionally the + contact info for each author, etc. + +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. Specification -- The technical specification should describe the + syntax and semantics of any new language feature. The + specification should be detailed enough to allow competing, + interoperable implementations for any of the current Python + platforms (CPython, Jython, Python .NET). + +5. Motivation -- The motivation is critical for GLEPs that want to + change the Python language. It should clearly explain why the + existing language specification is inadequate to address the + problem that the GLEP solves. GLEP submissions without sufficient + motivation may be rejected outright. + +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 languages. + + The rationale should provide evidence of consensus within the + community and discuss important objections or concerns raised + during discussion. + +7. Backwards Compatibility -- All GLEPs that introduce backwards + incompatibilities must include a section describing these + incompatibilities and their severity. The GLEP must explain how the + author proposes to deal with these incompatibilities. 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. + + The final implementation must include test code and documentation + appropriate for either the Python language reference or the + standard library reference. + + +GLEP Formats and Templates +========================= + +There are two GLEP formats available to authors: plaintext and +reStructuredText_. + +Plaintext GLEPs are written in plain ASCII text, contain minimal +structural markup, and should adhere to a rigid style. GLEP 9 contains +a boilerplate template [3]_ you can use to get started writing your +plaintext GLEP. + +ReStructuredText_ GLEPs allow for rich markup that is still quite easy +to read, but results in much better-looking and more functional HTML. +GLEP 12 contains a boilerplate template [4]_ for use with +reStructuredText GLEPs. + +There is a Python script that converts both styles of GLEPs to HTML for +viewing on the web [5]_. Parsing and conversion of plaintext GLEPs is +self-contained within the script. reStructuredText GLEPs are parsed +and converted by Docutils_ code called from the script. + + +GLEP Header Preamble +=================== + +Each GLEP must begin with an RFC 822 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. :: + + GLEP: <pep number> + Title: <pep title> + Version: <cvs version string> + Last-Modified: <cvs date string> + Author: <list of authors' real names and optionally, email addrs> + * Discussions-To: <email address> + Status: <Draft | Active | Accepted | Deferred | Rejected | + Final | Replaced> + Type: <Informational | Standards Track> + * Content-Type: <text/plain | text/x-rst> + * Requires: <pep numbers> + Created: <date created on, in dd-mmm-yyyy format> + * Python-Version: <version number> + Post-History: <dates of postings to python-list and python-dev> + * Replaces: <pep number> + * Replaced-By: <pep number> + +The Author header lists the names, and optionally the email addresses +of all the authors/owners of the GLEP. The format of the Author header +value must be + + Random J. User <address@dom.ain> + +if the email address is included, and just + + Random J. User + +if the address is not given. For historical reasons the format +"address@dom.ain (Random J. User)" may appear in a GLEP, however new +GLEPs must use the mandated format above, and it is acceptable to +change to this format when GLEPs are updated. + +If there are multiple authors, each should be on a separate line +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 python-list or python-dev email mailing lists. 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. The +acceptable values are "text/plain" for plaintext GLEPs (see GLEP 9 [3]_) +and "text/x-rst" for reStructuredText GLEPs (see GLEP 12 [4]_). +Plaintext ("text/plain") is the default if no Content-Type header is +present. + +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 python-list and/or python-dev. Both +headers should be in dd-mmm-yyyy format, e.g. 14-Aug-2001. + +Standards Track GLEPs must have a Python-Version header which indicates +the version of Python that the feature will be released with. +Informational GLEPs do not need a Python-Version header. + +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. + + +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 SourceForge `bug manager`_ or better +yet, the SourceForge `patch manager`_ so that your changes don't get +lost. If the GLEP author is a SF developer, assign the bug/patch to +him, otherwise assign it to the GLEP editor. + +When in doubt about where to send your changes, please check first +with the GLEP author and/or GLEP editor. + +GLEP authors who are also SF committers, can update the GLEPs themselves +by using "cvs commit" to commit their changes. Remember to also push +the formatted GLEP text out to the web by doing the following:: + + % python pep2html.py -i NUM + +where NUM is the number of the GLEP you want to push out. See :: + + % python pep2html.py --help + +for details. + + +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 +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 <peps@python.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 :). + + +References and Footnotes +======================== + +.. _PEP-0001: http://www.python.org/peps/pep-0001.html +.. [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 SourceForge web site at + http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/python/python/nondist/peps/ + +.. [2] GLEP 2, Procedure for Adding New Modules, Faassen + (http://www.python.org/peps/pep-0002.html) + +.. [3] GLEP 9, Sample Plaintext GLEP Template, Warsaw + (http://www.python.org/peps/pep-0009.html) + +.. [4] GLEP 12, Sample reStructuredText GLEP Template, Goodger, Warsaw + (http://www.python.org/peps/pep-0012.html) + +.. [5] The script referred to here is pep2html.py, which lives in the + same directory in the CVS tree as the GLEPs themselves. Try + ``pep2html.py --help`` for details. The URL for viewing GLEPs on + the web is http://www.python.org/peps/. + +.. _patch manager: + http://sourceforge.net/tracker/?group_id=5470&atid=305470 + +.. _feature request tracker: + http://sourceforge.net/tracker/?atid=355470&group_id=5470&func=browse + +.. _Open Publication License: http://www.opencontent.org/openpub/ + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html + +.. _Docutils: http://docutils.sourceforge.net/ + +.. _bug manager: + http://sourceforge.net/tracker/?group_id=5470&atid=105470 + + +Copyright +========= + +This document has been placed in the public domain. |