xeps/xep-README.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE jep SYSTEM '../jep.dtd' [
  <!ENTITY % ents SYSTEM '../jep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='../jep.xsl'?>
<jep>
<header>
  <title>JEP Editor README</title>
  <abstract>This document describes work processes followed by the JEP Editor.</abstract>
  &LEGALNOTICE;
  <number>README</number>
  <status>Experimental</status>
  <type>Procedural</type>
  <jig>N/A</jig>
  <approver>N/A</approver>
  <dependencies>
    <spec>JEP-0001</spec>
    <spec>JEP-0053</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>N/A</shortname>
  <author>
    <firstname>Peter</firstname>
    <surname>Saint-Andre</surname>
    <email>stpeter@jabber.org</email>
    <jid>stpeter@jabber.org</jid>
  </author>
  <revision>
    <version>0.5</version>
    <date>2005-05-26</date>
    <initials>psa</initials>
    <remark>Adjusted to reflect ProtoJEP status.</remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2005-03-16</date>
    <initials>psa</initials>
    <remark>Converted to JEP format; adjusted to reflect server move.</remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2004-10-22</date>
    <initials>psa</initials>
    <remark>Clarified schema handling.</remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2004-10-11</date>
    <initials>psa</initials>
    <remark>Defined Jabber Registrar processes.</remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2004-10-01</date>
    <initials>psa</initials>
    <remark>Initial version.</remark>
  </revision>
</header>

<section1 topic='Overview' anchor='overview'>

<p>Since the inception of the &JSF;, the &EDITOR; has been Peter Saint-Andre. However, if he gets hit by a bus or is replaced by someone else, this document may prove useful.</p>
<p>The JEP Editor manages the JEP process as defined in &jep0001;. In addition, the JEP Editor functions as the Jabber Registrar as defined in &jep0053;. Read those documents first, since this README focuses on mechanics rather than philosophy.</p>

</section1>
<section1 topic='JEP Processes' anchor='edprocesses'>

<p>There are several JEP-related functions performed by the JEP Editor:</p>
<ol>
  <li>Accepting a JEP</li>
  <li>Updating a JEP</li>
  <li>Deferring a JEP</li>
  <li>Retracting a JEP</li>
  <li>Issuing a Last Call</li>
  <li>Counting Council Votes</li>
  <li>Advancing a JEP</li>
</ol>
<p>These functions are specified below.</p>

<section2 topic='Accepting a JEP' anchor='accepting'>
<p>Periodically, people send mail to editor@jabber.org with new proposals. Here is how to process such submissions.</p>
<ol>
  <li>Receive proposal from author.</li>
  <li>Give it a descriptive filename that does <em>not</em> include the string 'jep' or a JEP number.</li>
  <li>Set the version to 0.0.1 if no version found.</li>
  <li>Set the status to ProtoJEP.</li>
  <li>Convert XML to HTML and check the results for accuracy.</li>
  <li>Place HTML at http://www.jabber.org/jeps/inbox/ (/var/www/jabber.org/jeps/inbox/)</li>
  <li>Place XML in the editor's working CVS directory on webserver (e.g., ~/cvs/jeps/inbox/docname.xml) </li>
  <li>Send a note to the Standards-JIG list by running the "protojep.py" script.</li>
  <li>Wait until the Council decides whether to accept the proposal as a JEP (this may involve poking the Council Chair).</li>
  <li>If rejected, retain in the "inbox".</li>
  <li>
    <p>If accepted, do the following:</p>
    <ol>
      <li>Assign the JEP the next available number in the JEP series.</li>
      <li>Modify the &lt;number/&gt; element in the XML file.</li>
      <li>Set the version to 0.1.</li>
      <li>Set the status to Experimental.</li>
      <li>Check the file for egregious errors.</li>
      <li>Add the directory and XML file to the "jeps" CVS module.</li>
      <li>Add a reference for the new JEP in the jep.ent file.</li>
      <li>Update CVS on the server.</li>
      <li>Run the "gen.sh" script.</li>
      <li>Run the "announce.py" script (see below), which updates the database and sends a message to the Standards-JIG list.</li>
      <li>Redirect the "inbox" file to the new JEP URL.</li>
    </ol>
  </li>
</ol>

</section2>
<section2 topic='Updating a JEP' anchor='updating'>
<p>Once a JEP has been published, it will be periodically updated in CVS, and sometimes those changes are significant enough to warrant a new version (e.g., version 0.2 after 0.1). Often a request to release a new version will come from the JEP author, sometimes from the Council (e.g., after the JEP has reached version 1.0 or version 2.0). Here is how to update JEPs.</p>
<ol>
  <li>Compile the file locally and check the content for accuracy (including the correct date and version number).</li>
  <li>Check your changes into CVS.</li>
  <li>Update CVS on the server.</li>
  <li>Run the "archive.sh" script to put the previous JEP version in the "attic".</li>
  <li>Run the "gen.sh" script.</li>
  <li>Run the "announce.py" script.</li>
</ol>

</section2>
<section2 topic='Deferring a JEP' anchor='deferring'>
<p>The status of a JEP shall be automatically changed to Deferred if a new version has not been released in 6 months, except if the JEP is actively in the Council queue for consideration of issuance of a Last Call. Here is the process.</p>
<ol>
  <li>Change the &lt;status/&gt; element to "Deferred" in the XML file.</li>
  <li>Check your changes into CVS (note: do not modify the version number!).</li>
  <li>Update CVS on the server.</li>
  <li>Run the "gen.sh" script.</li>
  <li>Run the "deferred.py" script.</li>
</ol>

</section2>
<section2 topic='Retracting a JEP' anchor='retracting'>
<p>Sometimes an author retracts a JEP because it is no longer worthy of consideration. Here is the process.</p>
<ol>
  <li>Change the &lt;status/&gt; element to "Retracted" in the XML file.</li>
  <li>Modify the &lt;abstract/&gt; element with appropriate content (see existing Retracted JEPs).</li>
  <li>Add a new revision block with an incremented version number, explaining that the JEP has been Retracted and why (see existing Retracted JEPs).</li>
  <li>Check your changes into CVS.</li>
  <li>Update CVS on the server.</li>
  <li>Run the "gen.sh" script.</li>
  <li>Run the "announce.py" script.</li>
</ol>

</section2>
<section2 topic='Issuing a Last Call' anchor='lastcall'>
<p>The Jabber Council determines whether and when to issue a Last Call on an Experimental JEP. Here is the process.</p>
<ol>
  <li>Receive notice from the Council Chair that a Last Call shall be issued.</li>
  <li>Determine the ending date, which must be at least 10 days in the future and usually is 2 weeks (sometimes 3 weeks if much discussion is expected).</li>
  <li>Change the &lt;status/&gt; element to "Proposed" in the XML file.</li>
  <li>Check your changes into CVS.</li>
  <li>Update CVS on the server.</li>
  <li>Run the "lastcall.py" script, which updates the database and sends a message to the Standards-JIG list.</li>
  <li>Review the Jabber Registrar Considerations section to ensure accuracy.</li>
</ol>

</section2>
<section2 topic='Counting Council Votes' anchor='councilvotes'>
<p>The JEP Editor is responsible for counting the votes of Council members. The process is as follows.</p>
<ol>
  <li>Inform the Council of the vote (see examples in the council@jabber.org archives).</li>
  <li>Monitor the Council list and Council meetings for votes.</li>
  <li>Update the votes XML file contained in the "council" CVS module.</li>
  <li>Check your changes into CVS.</li>
  <li>Update CVS on the server.</li>
  <li>Run the "gen.sh" script in the "council" module (don't confuse this with the JEP gen.sh script).</li>
  <li>When all Council members have voted, update the JEP accordingly (see below on Advancing a JEP).</li>
</ol>

</section2>
<section2 topic='Advancing a JEP' anchor='advancing'>
<p>When the Council approves a JEP, it advances to either Draft (Standards Track JEPs) or Active (other JEP types). Here is the process.</p>
<ol>
  <li>Change the &lt;status/&gt; element to "Active" or "Draft" as appropriate.</li>
  <li>Add a new revision block with a version number of "1.0" (see existing JEPs for appropriate remarks).</li>
  <li>If there are any XML schemas associated with the JEP, do the following:
    <ol>
      <li>Add an annotation to each schema (see existing examples).</li>
      <li>In the directory for this JEP, create one .xsd file for each schema.</li>
      <li>For each schema, add a &lt;schemaloc/&gt; element to the JEP file.</li>
      <li>Create a /var/www/jabber.org/protocol/shortname/ directory on the server (replace "shortname" with the short name of the JEP).</li>
      <li>Update the "schemagen.sh" script.</li>
    </ol>
  </li>
  <li>Add the protocol namespace (if any) to the protocol namespaces registry and complete any other Jabber Registrar actions called for in the JEP (see below).</li>
  <li>Check your changes into CVS.</li>
  <li>Update CVS on the server.</li>
  <li>Run the "archive.sh" script to put the previous JEP version in the "attic".</li>
  <li>Run the "schemagen.sh" script if appropriate.</li>
  <li>Run the "gen.sh" script.</li>
  <li>Run the "announce.py" script.</li>
  <li>Add a link to JEP from the appropriate section of the http://www.jabber.org/protocol/ page.</li>
</ol>

</section2>
</section1>
<section1 topic='Jabber Registrar Processes' anchor='regprocesses'>

<section2 topic='Advancing a JEP' anchor='reg-advance'>
<p>Registry files are contained in the "registry" CVS module. In general, there are several files that may need to be updated when a JEP advances to Active or Draft. In particular, most JEPs specify one or more protocol namespaces, which need to be added to the namespaces.xml file in the "registry" module. Refer to the list of registries at http://www.jabber.org/registrar/ in order to determine which other registries may need to be updated. The reg.ent file will probably need to be updated as well. Once the Registrar actions have been completed, update the text of the JEP's Jabber Registrar Considerations section accordingly (e.g., to change "shall include" to "includes").</p>

</section2>
<section2 topic='Creating a New Registry' anchor='reg-newreg'>
<p>A JEP may call for one or more new registries to be created. If so, carefully review the Jabber Registrar Considerations section of the JEP before it advances to Draft or Active in order to provide appropriate feedback to the JEP author. (Alternatively, make the changes directly in the JEP file in consultation with the author.)</p>
<p>When creating a new registry, it is best to copy the DTD, XML, and XSL files for an existing registry, then modify them in accordance with the definition of the new registry in the relevant JEP. The gen.sh script will need to be updated to reflect the existence of the new registry, as will the index file for the http://www.jabber.org/registrar/ web page.</p>
<p>Check all your changes into CVS, update your CVS directory on the web server, and run the gen.sh script to update the Jabber Registrar web pages.</p>

</section2>
</section1>
<section1 topic='Tools' anchor='tools'>

<section2 topic='XML Processing' anchor='tools-xml'>
<p>In order to convert XML files into HTML and other formats, the JEP Editor currently uses the xsltproc tool, which is part of libxml2 (created by Daniel Veillard). This tool is extremely handy and it is recommended that use of xsltproc be continued, especially since the shell scripts (described below) make calls to xsltproc.</p>

</section2>
<section2 topic='XSL Transformations' anchor='tools-xsl'>
<p>Most the "magic" behind creating the HTML-formatted JEPs, as well as the IETF-style reference files, is perfomed by XSL stylesheets. The main file here is jep.xsl, although ref.xsl is used to create the reference files. A future version of this README may explain these files in more depth.</p>

</section2>
<section2 topic='Entity References' anchor='tools-refs'>
<p>The jep.ent file contains handy references that can be incorporated into any JEP XML document, thus providing a centralized location for various document references. The JEP Editor must keep this file up to date (e.g., by adding all new JEPs to it), and should be the only person who makes changes to the file.</p>

</section2>
<section2 topic='Python Scripts' anchor='tools-python'>
<p>Several Python scripts are under source control. These are:</p>
<ol>
  <li>
    <p>announce.py</p>
    <p>This script announces a new version of a JEP by updating the database and sending a message to standards-jig@jabber.org.</p>
  </li>
  <li>
    <p>deferrred.py</p>
    <p>This script updates the database and sends a message to standards-jig@jabber.org when the status of a JEP is changed to Deferred. Before running this script, make sure that you modify the &lt;status/&gt; element in the JEP itself and run the gen.sh shell script.</p>
  </li>
  <li>
    <p>lastcall.py</p>
    <p>This script announces a Last Call for a JEP by updating the database and sending a message to standards-jig@jabber.org.</p>
  </li>
  <li>
    <p>protojep.py</p>
    <p>This script announces availability of a new "proto-JEP" (i.e., a document not yet accepted as a JEP by the Jabber Council) by sending a message to standards-jig@jabber.org. Before running this script, place the new proto-JEP so that it is available at http://www.jabber.org/jeps/inbox/ (normally this is done by running 'xsltproc inbox/docname.xml > /var/www/jabber.org/jeps/inbox/docname.html' from the editor's working CVS directory on the web server).</p>
  </li>
</ol>

</section2>
<section2 topic='Shell Scripts' anchor='tools-shell'>
<p>Several shell scripts are under source control. These are:</p>
<ol>
  <li>
    <p>all.sh</p>
    <p>This script converts all JEP XML files into HTML. Use this if the jep.xsl file changes in ways that affect all JEPs. But make sure that CVS is synced up first -- you don't want to be publishing interim versions of JEPs!</p>
  </li>
  <li>
    <p>archive.sh</p>
    <p>This script archives the version of a JEP currently on the website. Run this script before publishing a new version!</p>
  </li>
  <li>
    <p>gen.sh</p>
    <p>This script converts one JEP XML file into HTML. Run this script before announcing a new version. This script can also be used for minor edits to the current version.</p>
  </li>
  <li>
    <p>schemagen.sh</p>
    <p>This script updates all of the XML schemas located at http://www.jabber.org/protocol/ (more accurately, the subdirectories there). Update this file every time a protocol JEP with an associated schema advances to Active or Draft.</p>
  </li>
</ol>

</section2>
</section1>
</jep>