[Foundation] JIG's Proposal

[Rahul Dave]

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.