[Foundation] JIG's Proposal
Rahul Dave
rahul at reno.cis.upenn.edu
Wed May 23 18:59:35 CDT 2001
JEEP: 1
Title: JEEP Purpose and Guidelines
Version: $Revision: 1.2 $
Author: rahul at mozdev.org (Rahul Dave, aka tig)
Primary JIG: General
Secondary JIGS: None
Status: Draft
Type: Informational
Created: 33-May-2001
Post-History: 23-May-2001
What is a JEEP?
JEEP stands for Jabber EnhancEment Proposal. A JEEP is a design
document providing information to the Jabber community, or
describing a new feature for some Jabber component. The JEEP should provide a
concise technical specification of the feature and a rationale for
the feature.
We intend JEEPs 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
JEEP author is responsible for building consensus within the
community and documenting dissenting opinions.
Because the JEEPs are to be maintained as plain text files under CVS
control, their revision history is the historical record of the
feature proposal[1].
Kinds of JEEPs
There are two kinds of JEEPs. A standards track JEEP describes a
new feature or implementation for a Jabber Component. An informational JEEP
describes a Python design issue, or provides general guidelines or
information to the Python community, but does not propose a new
feature.
JEEP Work Flow
The JEEP editor, Rahul Dave <rahul at mozdev.org>, assigns numbers
for each JEEP and changes its status.
The JEEP process begins with a new idea for Jabber. Each JEEP must
have a champion(s) -- someone who writes the JEEP using the style and
format described below, shepherds the discussions in the
appropriate forums, which are one or more JIG's
and attempts to build community consensus
around the idea. The JEEP champion (a.k.a. Author) should first
attempt to ascertain whether the idea is JEEP-able. Small
enhancements or patches often don't need a JEEP and can be injected
into the Jabber development work flow with a patch submission to
the maintainer.
The JEEP champion then emails the JEEP editor with a proposed title
and a rough, but fleshed out, draft of the JEEP. This draft must
be written in JEEP style as described below.
If the JEEP editor approves (on style and JEEPability, not content, as this person
is by no means an expert on the subject of the JEEP), he will assign the JEEP a
number, label it as standards track or informational, give it status 'draft',
and create and check-in the initial draft of the JEEP into a JEEP CVS. The JEEP
editor will not unreasonably deny a JEEP. Reasons for denying JEEP
status include duplication of effort, not being in the prescribed style,
or not in keeping with the Jabber philosophy. The head of the JIG that the JEEP
belongs to, and if there is a dispute, the BDFL
(Benevolent Dictator for Life, Jeremie Miller
<jeremie at jabber.org>) can be consulted during the approval phase,
and is the final arbitrator of the draft's JEEP-ability.
The author of the JEEP is then responsible for posting the JEEP to
the community JIG forums, and marshaling community support for it. As
updates are necessary, the JEEP author can check in new versions if
they have CVS commit permissions, or can email new JEEP versions to
the JEEP editor for committing.
Standards track JEEPs consists of two parts, a design document and
a reference implementation. The JEEP should be reviewed and
accepted before a reference implementation is begun, unless a
reference implementation will aid people in studying the JEEP.
Standards Track JEEPs must include an implementation - in the form
of code, patch, or URL to same - before it can be considered
Final.
JEEP authors are responsible for collecting community feedback on a
JEEP before submitting it for review. A JEEP that has not been
discussed the primary JIG list
will not be accepted. However, wherever possible, long open-ended
discussions on public mailing lists should be avoided. A better
strategy is to encourage public feedback directly to the JEEP
author, who collects and integrates the comments back into the
JEEP.
Once the authors have completed a JEEP, they must inform the JEEP
editor that it is ready for review. JEEPs are reviewed by the BDFL
and primary and secondary JIG heads, who may accept or reject a JEEP or send
it back to the author(s) for revision.
Once a JEEP has been accepted, the reference implementation must be
completed. When the reference implementation is complete and
accepted by the BDFL, or JIG head in the case of a non-core component,
the status will be changed to `Final.'
A JEEP can also be assigned status `Deferred.' The JEEP author or
editor can assign the JEEP this status when no progress is being
made on the JEEP. Once a JEEP is deferred, the JEEP editor can
re-assign it to draft status.
A JEEP 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.
JEEPs can also be replaced by a different JEEP, rendering the
original obsolete. This is intended for Informational JEEPs, where
version 2 of an API can replace version 1.
JEEP work flow is as follows:
Draft -> Accepted -> Final -> Replaced
^
+----> Rejected
v
Deferred
Some informational JEEPs may also have a status of `Active' if they
are never meant to be completed. E.g. JEEP 1.
What belongs in a successful JEEP?
Each JEEP should have the following parts:
1. Preamble -- RFC822 style headers containing meta-data about the
JEEP, including the JEEP number, a short descriptive title
(limited to a maximum of 38 characters), the names contact info
for each author, etc.
2. Abstract -- a short (~200 word) description of the technical
issue being addressed.
3. Copyright/public domain -- Each JEEP must either be explicitly
labelled in the public domain or the Open Publication
License[4].
4. Specification -- The technical specification should describe
the syntax and semantics of any new feature. The
specification should be detailed enough to allow competing,
interoperable implementations for any of the current Jabber
platforms (Clients, servers, or transports).
5. 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.
6. Reference Implementation -- The reference implementation must
be completed before any JEEP is given status 'Final,' but it
need not be completed before the JEEP 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.
JEEP Style
JEEPs are written in plain ASCII text, and should adhere to a
rigid style. There is a Python script that parses this style and
converts the plain text JEEP to HTML for viewing on the web[3].
Each JEEP must begin with an RFC822 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.
JEEP: <JEEP number>
Title: <JEEP title>
Version: <cvs version string>
Author: <list of authors' email and real name>
Primary JIG: Primary JIG in which this JEEP is proposed
* Secondary JIGS: Comma separated list of secondary jig names, no
comma if one, or "None"
* Discussions-To: <email address>
Status: <Draft | Active | Accepted | Deferred | Final | Replaced>
Type: <Informational | Standards Track>
* Requires: <JEEP numbers>
Created: <date created on, in dd-mmm-yyyy format>
* Jabber-Version: <version number>
Post-History: <dates of postings to appropriate JIG forums>
* Replaces: <JEEP number>
* Replaced-By: <JEEP number>
Standards track JEEPs must have a Jabber-Version: header which
indicates the version of Python that the feature will be released
with. Informational JEEPs do not need a Jabber-Version: header.
While a JEEP is in private discussions (usually during the initial
Draft phase), a Discussions-To: header will indicate the mailing
list or URL where the JEEP is being discussed. No Discussions-To:
header is necessary if the JEEP is being discussed privately with
the author, or on the python-list or python-dev email mailing
lists.
JEEPs may have a Requires: header, indicating the JEEP numbers that
this JEEP depends on.
JEEPs may also have a Replaced-By: header indicating that a JEEP has
been rendered obsolete by a later document; the value is the
number of the JEEP that replaces the current document. The newer
JEEP must have a Replaces: header containing the number of the JEEP
that it rendered obsolete.
JEEP headings must begin in column zero and the initial letter of
each word must be capitalized as in book titles. Acronyms should
be in all capitals. The body of each section must be indented 4
spaces. Code samples inside body sections should be indented a
further 4 spaces, and other indentation can be used as required to
make the text readable. You must use two blank lines between the
last line of a section's body and the next section heading.
Tab characters must never appear in the document at all. A JEEP
should include the Emacs stanza included by example in this JEEP.
A JEEP must contain a Copyright section, and it is strongly
recommended to put the JEEP in the public domain.
You should footnote any URLs in the body of the JEEP, and a JEEP
should include a References section with those URLs expanded.
References and Footnotes
[1] JEEP's are modeled(with this document shamelessy stolen from [2]) on
the Python Community's PEP's.
See http://python.sourceforge.net/peps/.
[2] This document is modelled after Python PEP-0,
see http://python.sourceforge.net/peps/pep-0001.html
[3] The script referred to here is JEEP2html.py, which lives in
the same directory in the CVS tree as the JEEPs themselves. Try
"JEEP2html.py --help" for details. (This is in the process of being
modified from the python one.)
Copyright
This document has been placed in the public domain.
More information about the Members
mailing list