diff options
Diffstat (limited to 'glep-1.txt')
| -rw-r--r-- | glep-1.txt | 410 |
1 files changed, 0 insertions, 410 deletions
diff --git a/glep-1.txt b/glep-1.txt deleted file mode 100644 index 80bffd0..0000000 --- a/glep-1.txt +++ /dev/null @@ -1,410 +0,0 @@ -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. |