moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

fixes 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@558 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-02-14 05:48:36 +00:00
parent 8e70248cb2
commit 04d5d24011
1 changed files with 56 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
xep-README.xml
View File

@ -55,13 +55,11 @@
</header> </header>
<section1 topic='Overview' anchor='overview'> <section1 topic='Overview' anchor='overview'>
<p>Since the inception of the &XSF;, 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>Since the inception of the &XSF;, 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 XMPP Extensions Editor manages the XMPP extensions process as defined in &xep0001;. In addition, the XMPP Extensions Editor functions as the XMPP Registrar as defined in &xep0053;. Read those documents first, since this README focuses on mechanics rather than philosophy.</p> <p>The XMPP Extensions Editor manages the XMPP extensions process as defined in &xep0001;. In addition, the XMPP Extensions Editor functions as the XMPP Registrar as defined in &xep0053;. Read those documents first, since this README focuses on mechanics instead of philosophy.</p>
</section1> </section1>
<section1 topic='Processes' anchor='edprocesses'>
<section1 topic='Processes' anchor='edprocesses'>
<p>There are several XEP-related functions performed by the XMPP Extensions Editor:</p> <p>There are several XEP-related functions performed by the XMPP Extensions Editor:</p>
<ol> <ol>
<li>Accepting a XEP</li> <li>Accepting a XEP</li>
@ -83,8 +81,8 @@
<li>Set the status to ProtoXEP.</li> <li>Set the status to ProtoXEP.</li>
<li>Convert XML to HTML and check the results for accuracy.</li> <li>Convert XML to HTML and check the results for accuracy.</li>
<li>Place HTML at http://www.xmpp.org/extensions/inbox/ (/var/www/xmpp.org/extensions/inbox/)</li> <li>Place HTML at http://www.xmpp.org/extensions/inbox/ (/var/www/xmpp.org/extensions/inbox/)</li>
<li>Place XML in the editor's working CVS directory on webserver (e.g., ~/cvs/xmpp/extensions/inbox/docname.xml) </li> <li>Place XML in the editor's working CVS directory on mailserver (e.g., ~/cvs/xmpp/extensions/docname.xml) </li>
<li>Send a note to the Standards list by running the "protoxep.py" script.</li> <li>Send a note to the Standards list by running the "inxep.py" script.</li>
<li>Wait until the Council decides whether to accept the proposal as a XEP (this may involve poking the Council Chair).</li> <li>Wait until the Council decides whether to accept the proposal as a XEP (this may involve poking the Council Chair).</li>
<li>If rejected, retain in the "inbox".</li> <li>If rejected, retain in the "inbox".</li>
<li> <li>
@ -95,40 +93,45 @@
<li>Set the version to 0.1.</li> <li>Set the version to 0.1.</li>
<li>Set the status to Experimental.</li> <li>Set the status to Experimental.</li>
<li>Check the file for egregious errors.</li> <li>Check the file for egregious errors.</li>
<li>Add the directory and XML file to the "xmpp/extensions" CVS module.</li> <li>Add the XML file to the 'extensions' directory in the "xmpp" CVS module.</li>
<li>Add a reference for the new XEP in the xep.ent file.</li> <li>Add a reference for the new XEP in the xep.ent file.</li>
<li>Update CVS on the server.</li> <li>Update CVS on the webserver.</li>
<li>Run the "gen.sh" script.</li> <li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "announce.py" script (see below), which updates the database and sends a message to the Standards list.</li> <li>Run the "dbupdate.py" script on the webserver.</li>
<li>Update CVS on the mailserver.</li>
<li>Run the "announce.py" script on the mailserver.</li>
<li>Redirect the "inbox" file to the new XEP URL.</li> <li>Redirect the "inbox" file to the new XEP URL.</li>
</ol> </ol>
</li> </li>
</ol> </ol>
</section2> </section2>
<section2 topic='Updating a XEP' anchor='updating'> <section2 topic='Updating a XEP' anchor='updating'>
<p>Once a XEP 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 document author, sometimes from the Council (e.g., after the XEP has reached version 1.0 or version 2.0). Here is how to update a XEP.</p> <p>Once a XEP 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 document author, sometimes from the Council (e.g., after the XEP has reached version 1.0 or version 2.0). Here is how to update a XEP.</p>
<ol> <ol>
<li>Compile the file locally and check the content for accuracy (including the correct date and version number).</li> <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>Check your changes into CVS.</li>
<li>Update CVS on the server.</li>
<li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li> <li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li>
<li>Run the "gen.sh" script.</li> <li>Update CVS on the webserver.</li>
<li>Run the "announce.py" script.</li> <li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Update CVS on the mailserver.</li>
<li>Run the "announce.py" script on the mailserver.</li>
</ol> </ol>
</section2> </section2>
<section2 topic='Deferring a XEP' anchor='deferring'> <section2 topic='Deferring a XEP' anchor='deferring'>
<p>The status of a XEP shall be automatically changed to Deferred if a new version has not been released in 6 months, except if the XEP is actively in the Council queue for consideration of issuance of a Last Call. Here is the process.</p> <p>The status of a XEP shall be automatically changed to Deferred if a new version has not been released in 6 months, except if the XEP is actively in the Council queue for consideration of issuance of a Last Call. Here is the process.</p>
<ol> <ol>
<li>Change the &lt;status/&gt; element to "Deferred" in the XML file.</li> <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>Check your changes into CVS (note: do not modify the version number!).</li>
<li>Update CVS on the server.</li> <li>Update CVS on the webserver.</li>
<li>Run the "gen.sh" script.</li> <li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "deferred.py" script.</li> <li>Update CVS on the mailserver.</li>
<li>Run the "deferred.py" script on the mailserver.</li>
</ol> </ol>
</section2> </section2>
<section2 topic='Retracting a XEP' anchor='retracting'> <section2 topic='Retracting a XEP' anchor='retracting'>
<p>Sometimes an author retracts a XEP because it is no longer worthy of consideration. Here is the process.</p> <p>Sometimes an author retracts a XEP because it is no longer worthy of consideration. Here is the process.</p>
<ol> <ol>
@ -136,12 +139,14 @@
<li>Modify the &lt;abstract/&gt; element with appropriate content (see existing Retracted XEPs).</li> <li>Modify the &lt;abstract/&gt; element with appropriate content (see existing Retracted XEPs).</li>
<li>Add a new revision block with an incremented version number, explaining that the XEP has been Retracted and why (see existing Retracted XEPs).</li> <li>Add a new revision block with an incremented version number, explaining that the XEP has been Retracted and why (see existing Retracted XEPs).</li>
<li>Check your changes into CVS.</li> <li>Check your changes into CVS.</li>
<li>Update CVS on the server.</li> <li>Update CVS on the webserver.</li>
<li>Run the "gen.sh" script.</li> <li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "announce.py" script.</li> <li>Run the "dbupdate.py" script on the webserver.</li>
<li>Update CVS on the mailserver.</li>
<li>Run the "announce.py" script on the mailserver.</li>
</ol> </ol>
</section2> </section2>
<section2 topic='Issuing a Last Call' anchor='lastcall'> <section2 topic='Issuing a Last Call' anchor='lastcall'>
<p>The XMPP Council determines whether and when to issue a Last Call on an Experimental XEP. Here is the process.</p> <p>The XMPP Council determines whether and when to issue a Last Call on an Experimental XEP. Here is the process.</p>
<ol> <ol>
@ -149,25 +154,28 @@
<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>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>Change the &lt;status/&gt; element to "Proposed" in the XML file.</li>
<li>Check your changes into CVS.</li> <li>Check your changes into CVS.</li>
<li>Update CVS on the server.</li> <li>Update CVS on the webserver.</li>
<li>Run the "lastcall.py" script, which updates the database and sends a message to the Standards list.</li> <li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Update CVS on the mailserver.</li>
<li>Run the "lastcall.py" script on the mailserver.</li>
<li>Review the XMPP Registrar Considerations section to ensure accuracy.</li> <li>Review the XMPP Registrar Considerations section to ensure accuracy.</li>
</ol> </ol>
</section2> </section2>
<section2 topic='Counting Council Votes' anchor='councilvotes'> <section2 topic='Counting Council Votes' anchor='councilvotes'>
<p>The XMPP Extensions Editor is responsible for counting the votes of Council members. The process is as follows.</p> <p>The XMPP Extensions Editor is responsible for counting the votes of Council members. The process is as follows.</p>
<ol> <ol>
<li>Inform the Council of the vote (see examples in the council@jabber.org archives).</li> <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>Monitor the Council list and Council meetings for votes.</li>
<li>Update the votes XML file contained in the "council" CVS module.</li> <li>Update the appropriate Council tally file in the 'council' directory.</li>
<li>Check your changes into CVS.</li> <li>Check your changes into CVS.</li>
<li>Update CVS on the server.</li> <li>Update CVS on the server.</li>
<li>Run the "gen.sh" script in the "council" module (don't confuse this with the XEP gen.sh script).</li> <li>Run the "gen.sh" script in the 'council' directory (don't confuse this with the XEP gen.sh script).</li>
<li>When all Council members have voted, update the XEP accordingly (see below on Advancing a XEP).</li> <li>When all Council members have voted, update the XEP accordingly (see below on Advancing a XEP).</li>
</ol> </ol>
</section2> </section2>
<section2 topic='Advancing a XEP' anchor='advancing'> <section2 topic='Advancing a XEP' anchor='advancing'>
<p>When the Council approves a XEP, it advances to either Draft (Standards Track XEPs) or Active (other XEP types). Here is the process.</p> <p>When the Council approves a XEP, it advances to either Draft (Standards Track XEPs) or Active (other XEP types). Here is the process.</p>
<ol> <ol>
@ -176,49 +184,51 @@
<li>If there are any XML schemas associated with the XEP, do the following: <li>If there are any XML schemas associated with the XEP, do the following:
<ol> <ol>
<li>Add an annotation to each schema (see existing examples).</li> <li>Add an annotation to each schema (see existing examples).</li>
<li>In the 'schemas/' directory, create one .xsd file for each schema.</li> <li>In the 'schemas' directory, create one .xsd file for each schema.</li>
<li>For each schema, add a &lt;schemaloc/&gt; element to the XEP file.</li> <li>For each schema, add a &lt;schemaloc/&gt; element to the XEP file.</li>
<li>Update the "schemagen.sh" script.</li>
</ol> </ol>
</li> </li>
<li>Add the protocol namespace (if any) to the protocol namespaces registry and complete any other XMPP Registrar actions called for in the XEP (see below).</li> <li>Add the protocol namespace (if any) to the protocol namespaces registry and complete any other XMPP Registrar actions called for in the XEP (see below).</li>
<li>Check your changes into CVS.</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 XEP version in the "attic".</li> <li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li>
<li>Run the "schemagen.sh" script if appropriate.</li> <li>Update CVS on the webserver.</li>
<li>Run the "gen.sh" script.</li> <li>Run the "gen.sh" script.</li>
<li>Run the "announce.py" script.</li> <li>Run the "dbupdate.py" script on the webserver.</li>
<li>Update CVS on the mailserver.</li>
<li>Run the "announce.py" script on the mailserver.</li>
</ol> </ol>
</section2> </section2>
</section1> </section1>
<section1 topic='XMPP Registrar Processes' anchor='regprocesses'> <section1 topic='XMPP Registrar Processes' anchor='regprocesses'>
<section2 topic='Advancing a XEP' anchor='reg-advance'> <section2 topic='Advancing a XEP' 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 XEP advances to Active or Draft. In particular, most XEPs 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.xmpp.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 XEP's XMPP Registrar Considerations section accordingly (e.g., to change "shall include" to "includes").</p> <p>Registry files are contained in the 'registry' directory. In general, there are several files that may need to be updated when a XEP advances to Active or Draft. In particular, most XEPs specify one or more protocol namespaces, which need to be added to the namespaces.xml file in the 'registry' directory. Refer to the list of registries at http://www.xmpp.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 XEP's XMPP Registrar Considerations section accordingly (e.g., to change "shall include" to "includes").</p>
</section2> </section2>
<section2 topic='Creating a New Registry' anchor='reg-newreg'> <section2 topic='Creating a New Registry' anchor='reg-newreg'>
<p>A XEP may call for one or more new registries to be created. If so, carefully review the XMPP Registrar Considerations section of the XEP before it advances to Draft or Active in order to provide appropriate feedback to the XEP author. (Alternatively, make the changes directly in the XEP file in consultation with the author.)</p> <p>A XEP may call for one or more new registries to be created. If so, carefully review the XMPP Registrar Considerations section of the XEP before it advances to Draft or Active in order to provide appropriate feedback to the XEP author. (Alternatively, make the changes directly in the XEP 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 XEP. 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.xmpp.org/registrar/ web page.</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 XEP. 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.xmpp.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 XMPP Registrar web pages.</p> <p>Check all your changes into CVS, update the editor's CVS directory on the webserver, and run the gen.sh script to update the XMPP Registrar web pagesr. Then update the editor's CVS directory on the mailserver and run the announce.py script to send an announcement to the Standards list.</p>
</section2> </section2>
</section1> </section1>
<section1 topic='Tools' anchor='tools'> <section1 topic='Tools' anchor='tools'>
<section2 topic='XML Processing' anchor='tools-xml'> <section2 topic='XML Processing' anchor='tools-xml'>
<p>In order to convert XML files into HTML and other formats, the XMPP Extensions 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> <p>In order to convert XML files into HTML and other formats, the XMPP Extensions 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>
<section2 topic='XSL Transformations' anchor='tools-xsl'> <section2 topic='XSL Transformations' anchor='tools-xsl'>
<p>Most the "magic" behind creating the HTML-formatted XEPs, as well as the IETF-style reference files, is perfomed by XSL stylesheets. The main file here is xep.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> <p>Most the "magic" behind creating the HTML-formatted XEPs, as well as the IETF-style reference files, is perfomed by XSL stylesheets. The main file here is xep.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>
<section2 topic='Entity References' anchor='tools-refs'> <section2 topic='Entity References' anchor='tools-refs'>
<p>The xep.ent file contains handy references that can be incorporated into any XEP XML document, thus providing a centralized location for various document references. The XMPP Extensions Editor must keep this file up to date (e.g., by adding all new XEPs to it), and should be the only person who makes changes to the file.</p> <p>The xep.ent file contains handy references that can be incorporated into any XEP XML document, thus providing a centralized location for various document references. The XMPP Extensions Editor must keep this file up to date (e.g., by adding all new XEPs to it), and should be the only person who makes changes to the file.</p>
</section2> </section2>
<section2 topic='Python Scripts' anchor='tools-python'> <section2 topic='Python Scripts' anchor='tools-python'>
<p>Several Python scripts are under source control. These are:</p> <p>Several Python scripts are under source control. These are:</p>
<ol> <ol>
@ -236,11 +246,11 @@
</li> </li>
<li> <li>
<p>protoxep.py</p> <p>protoxep.py</p>
<p>This script announces availability of a new "proto-XEP" (i.e., a document not yet accepted as a XEP by the XMPP Council) by sending a message to standards@xmpp.org. Before running this script, place the new proto-XEP so that it is available at http://www.xmpp.org/extensions/inbox/ (normally this is done by running 'xsltproc inbox/docname.xml > /var/www/xmpp.org/extensions/inbox/docname.html' from the editor's working CVS directory on the web server).</p> <p>This script announces availability of a new "proto-XEP" (i.e., a document not yet accepted as a XEP by the XMPP Council) by sending a message to standards@xmpp.org. Before running this script, place the new proto-XEP so that it is available at http://www.xmpp.org/extensions/inbox/ (normally this is done by running 'xsltproc inbox/docname.xml > /var/www/xmpp.org/extensions/inbox/docname.html' from the editor's working CVS directory on the webserver).</p>
</li> </li>
</ol> </ol>
</section2> </section2>
<section2 topic='Shell Scripts' anchor='tools-shell'> <section2 topic='Shell Scripts' anchor='tools-shell'>
<p>Several shell scripts are under source control. These are:</p> <p>Several shell scripts are under source control. These are:</p>
<ol> <ol>
@ -261,7 +271,8 @@
<p>This script updates all of the XML schemas located at &lt;http://www.xmpp.org/schemas/&gt;. Update this file every time a protocol XEP with an associated schema advances to Active or Draft.</p> <p>This script updates all of the XML schemas located at &lt;http://www.xmpp.org/schemas/&gt;. Update this file every time a protocol XEP with an associated schema advances to Active or Draft.</p>
</li> </li>
</ol> </ol>
</section2> </section2>
</section1> </section1>
</xep> </xep>