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

0.8 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3648 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2009-11-19 18:42:17 +00:00
parent 133df48a70
commit b564bcb3bc
1 changed files with 112 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
xep-README.xml
View File

@ -22,6 +22,12 @@
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>0.8</version>
<date>2009-11-19</date>
<initials>psa</initials>
<remark><p>Updated to reflect newer processes and provide more complete coverage of XEP Editor and XMPP Registrar responsibilities.</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2008-07-16</date>
@ -67,11 +73,11 @@
</header>
<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 might prove useful.</p>
<p>The XMPP Extensions Editor (or, for short, XEP Editor) manages the XMPP extensions process as defined in &xep0001;. In addition, the XEP 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 topic='XEP Editor Processes' anchor='edprocesses'>
<section1 topic='XEP Editor Responsibilities' anchor='ed'>
<p>There are several XEP-related functions performed by the XEP Editor:</p>
<ol>
<li>Accepting a XEP</li>
@ -81,22 +87,28 @@
<li>Issuing a Last Call</li>
<li>Counting Council Votes</li>
<li>Advancing a XEP</li>
<li>Deprecating a XEP</li>
<li>Obsoleting a XEP</li>
<li>XEP Maintenance</li>
<li>List Administration</li>
<li>Radar Page</li>
</ol>
<p>These functions are specified below.</p>
<section2 topic='Accepting a XEP' anchor='accepting'>
<p>Periodically, people send email to editor@xmpp.org with new proposals. Here is how to process such submissions.</p>
<ol>
<li>Receive proposal from author.</li>
<li>Receive proposal from authors.</li>
<li>Send a reply to the author(s) in order to verify that, if the proposal is accepted, they will cede rights to the protocol in accordance with the XSF's IPR policy <link url='http://xmpp.org/extensions/ipr-policy.shtml'>http://xmpp.org/extensions/ipr-policy.shtml</link>.</li>
<li>Give it a descriptive filename that does <em>not</em> include the string 'xep' or a XEP number.</li>
<li>Set the version to 0.0.1 if no version found.</li>
<li>Set the version to 0.0.1 if no revision block is found.</li>
<li>Set the status to ProtoXEP.</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/ on the webserver)</li>
<li>Place XML in the editor's working Subversion directory on the webserver (e.g., ~/svn/xmpp/extensions/docname.xml) </li>
<li>Convert XML to HTML and check the results for accuracy in accordance with normal XEP formatting (see &xep0143;).</li>
<li>Place XML and HTML at http://xmpp.org/extensions/inbox/ (/var/www/vhosts/xmpp.org/extensions/inbox/ on the webserver)</li>
<li>Place XML in the editor's working Subversion directory on the webserver (e.g., ~/svn/xmpp/trunk/extensions/docname.xml) </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>If rejected, retain in the "inbox".</li>
<li>Wait until the Council decides whether to accept the proposal as a XEP (this might involve poking the Council Chair, attending Council meetings, and monitoring the Council discussion list).</li>
<li>If rejected, retain the XML and HTML files in the "inbox".</li>
<li>
<p>If accepted, do the following:</p>
<ol>
@ -109,9 +121,9 @@
<li>Add the file to the SVN repository.</li>
<li>Add a reference for the new XEP in the xep.ent file and check those changes into SVN.</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Run the "announce.py" script on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
<li>Redirect the "inbox" file to the new XEP URL.</li>
</ol>
</li>
@ -125,9 +137,9 @@
<li>Check your changes into SVN.</li>
<li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Run the "announce.py" script on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
@ -137,7 +149,8 @@
<li>Change the &lt;status/&gt; element to "Deferred" in the XML file.</li>
<li>Check your changes into SVN (note: do not modify the version number!).</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "deferred.py" script on the webserver.</li>
</ol>
</section2>
@ -151,9 +164,9 @@
<li>Check your changes into SVN.</li>
<li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Run the "announce.py" script on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
@ -165,8 +178,8 @@
<li>Change the &lt;status/&gt; element to "Proposed" in the XML file.</li>
<li>Check your changes into SVN.</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script on the webserver.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "lastcall.py" script on the webserver.</li>
<li>Review the XMPP Registrar Considerations section to ensure accuracy.</li>
</ol>
@ -175,12 +188,12 @@
<section2 topic='Counting Council Votes' anchor='councilvotes'>
<p>The XEP 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@xmpp.org mailing list archives).</li>
<li>Inform the Council of the vote (see examples in the council@xmpp.org mailing list archives or chatroom logs).</li>
<li>Monitor the Council list and Council meetings for votes.</li>
<li>Update the appropriate Council tally file in the 'council' directory.</li>
<li>Update the appropriate Council "tally_*.shtml" file in the 'council' directory.</li>
<li>Check your changes into SVN.</li>
<li>Update SVN on the server.</li>
<li>Run the "gen.sh" script in the 'council' directory (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.py script).</li>
<li>When all Council members have voted, update the XEP accordingly (see below on Advancing a XEP).</li>
</ol>
</section2>
@ -199,26 +212,83 @@
</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 SVN.</li>
<li>Run the "archive.sh" script to put the previous XEP version in the "attic".</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.sh" script.</li>
<li>Run the "dbupdate.py" script on the webserver.</li>
<li>Run the "gen.py" script.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
<li>Update the protocol pages at <link url='http://xmpp.org/protocols/'>http://xmpp.org/protocols/</link> to reflect advancement of the XEP.</li>
</ol>
</section2>
<section2 topic='Deprecating a XEP' anchor='deprecating'>
<p>The Council can decide to change the status of a XEP to Deprecated (e.g., when a new technology has been developed to supersede the old technology). Here is the process:</p>
<ol>
<li>Increment the version number.</li>
<li>Change the &lt;status/&gt; element to "Deprecated" in the XML file.</li>
<li>If instructed to do so by the Council, add an &lt;expires/&gt; element to the header.</li>
<li>Add a &lt;spec/&gt; child to the &lt;supersededby/&gt; element, pointing to the specification that supersedes this one.</li>
<li>Add a pointer to the superseding spec in the abstract and a new first paragraph of the XEP.</li>
<li>Check your changes into SVN.</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "announce.py" script on the webserver.</li>
</ol>
</section2>
<section2 topic='Obsoleting a XEP' anchor='obsoleting'>
<p>The Council can decide to change the status of a XEP from Deprecated to Obsolete. Here is the process:</p>
<ol>
<li>Increment the version number.</li>
<li>Change the &lt;status/&gt; element to "Obsolete" in the XML file.</li>
<li>If the file includes an &lt;expires/&gt; element in the header, remove it.</li>
<li>If appropriate, add a &lt;spec/&gt; child to the &lt;supersededby/&gt; element, pointing to the specification that supersedes this one.</li>
<li>If appropriate, add a pointer to the superseding spec in the abstract and a new first paragraph of the XEP.</li>
<li>Check your changes into SVN.</li>
<li>Update SVN on the webserver.</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Run the "archive.sh" script, which copies this published version to <link url='http://xmpp.org/extensions/attic/'>http://xmpp.org/extensions/attic/</link>.</li>
<li>Run the "announce.py" script on the webserver.</li>
</ol>
</section2>
<section2 topic='XEP Maintenance' anchor='maintenance'>
<p>At any time (even after a XEP has advanced to Draft or Final), it is appropriate for the XEP Editor to correct small errors in XEPs (typographical errors, XML errors in examples, etc.).</p>
<p>However, care must be taken in editing Draft and Final XEPs, because any material changes to such specifications need to be approved by the XMPP Council. See <cite>XEP-0001</cite> for details.</p>
<p>The XEP Editor can choose to perform more advanced maintenance of XEPs, such as validation of schemas, checking of examples, and copy editing in accordance with the styleguide in <cite>XEP-0143</cite>. Such work is best done while a XEP is still Experimental.</p>
</section2>
<section2 topic='List Administration' anchor='lists'>
<p>XEPs are discussed on the standards@xmpp.org email list, about which information is available at &lt;<link url='http://mail.jabber.org/mailman/listinfo/standards'>http://mail.jabber.org/mailman/listinfo/standards</link>&gt;. Traditionally the XEP Editor acts as an administrator for this list. In particular, email from editor@xmpp.org is held for approval on this list to prevent spammers from sending fake emails from the Editor. Before running the "announce.py" script, empty the queue of messages held for moderation; after running the script, approve the message generated by that script so that it is sent to the list.</p>
</section2>
<section2 topic='Radar Page' anchor='radar'>
<p>The XEP Editor maintains a "radar page" at <link url='http://wiki.xmpp.org/web/Radar'>http://wiki.xmpp.org/web/Radar</link>, which provides information about XEPs that are in the following states:</p>
<ul>
<li>Active, Draft, and Final XEPs that are under revision.</li>
<li>Draft XEPs that are undergoing a Call for Experience in preparation for advancement to Final.</li>
<li>Experimental XEPs that are undergoing a Last Call in preparation for advancement to Draft (or Active).</li>
<li>Experimental XEPs that are due to be automatically changed to Deferred because they have not been updated in 12+ months.</li>
</ul>
<p>The radar page is used by the Chair of the XMPP Council in preparing agendas for Council meetings.</p>
</section2>
</section1>
<section1 topic='XMPP Registrar Processes' anchor='regprocesses'>
<section1 topic='XMPP Registrar Responsibilities' anchor='reg'>
<section2 topic='Advancing a XEP' anchor='reg-advance'>
<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>
<p>Registry files are contained in the 'registry' directory. In general, there are several files that might 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://xmpp.org/registrar/ in order to determine which other registries might 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 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>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 SVN, update the editor's SVN directory on the webserver, run the gen.sh script to update the XMPP Registrar web pages, and run the announce.py script to send an announcement to the Standards list.</p>
<p>A XEP might 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://xmpp.org/registrar/ web page.</p>
<p>Check all your changes into SVN, update the editor's SVN directory on the webserver, run the gen.sh script to update the XMPP Registrar web pages, and run the announce.py script to send an announcement to the Standards list (see note about <link url='#lists'>List Administration</link>).</p>
</section2>
<section2 topic='Updating an Existing Registry' anchor='reg-update'>
<p>New versions of XEPs might provide modified registry data. The XEP Editor needs to be aware of changes to Draft and Final XEPs in order to make appropriate updates to existing registries. The registry itself shall not be changed until the new XEP version is approved by the XMPP Council.</p>
<p>The XMPP Registrar also periodically receives requests for additions to existing registrations outside of XEPs, either directly to registrar@xmpp.org or indirectly via standards@xmpp.org list. If the Registrar receives such a request directly, it shall send an email about the proposed registration to the standards@xmpp.org for public comment. If no objections are raised within a reasonable period of time, the Registrar shall update the relevant registry accordingly.</p>
</section2>
</section1>
@ -230,11 +300,11 @@
</section2>
<section2 topic='XSL Transformations' anchor='tools-xsl'>
<p>Most of the "magic" behind creating the HTML-formatted XEPs, as well as the IETF-style reference files, is perfomed by XSLT 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 of the "magic" behind creating the HTML-formatted XEPs, as well as the IETF-style reference files, is perfomed by XSLT stylesheets. The main file here is xep.xsl, although ref.xsl is used to create the reference files. A future version of this README might explain these files in more depth.</p>
</section2>
<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 XEP 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 XEP Editor keeps 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 topic='Python Scripts' anchor='tools-python'>
@ -242,11 +312,15 @@
<ol>
<li>
<p>announce.py</p>
<p>This script announces a new version of a XEP by updating the database and sending a message to standards@xmpp.org.</p>
<p>This script announces a new version of a XEP by sending a message to standards@xmpp.org (see note about <link url='#lists'>List Administration</link>).</p>
</li>
<li>
<p>deferrred.py</p>
<p>This script updates the database and sends a message to standards@xmpp.org when the status of a XEP is changed to Deferred. Before running this script, make sure that you modify the &lt;status/&gt; element in the XEP itself and run the gen.sh shell script.</p>
<p>deferred.py</p>
<p>This script updates the database and sends a message to standards@xmpp.org when the status of a XEP is changed to Deferred. Before running this script, make sure that you modify the &lt;status/&gt; element in the XEP itself and run the gen.py shell script.</p>
</li>
<li>
<p>gen.py</p>
<p>This script converts one XEP XML file into HTML, and updates the XEP "database". 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>lastcall.py</p>
@ -254,7 +328,7 @@
</li>
<li>
<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 SVN directory on the webserver).</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://xmpp.org/extensions/inbox/ (normally this is done by running 'xsltproc inbox/docname.xml > /var/www/vhosts/xmpp.org/extensions/inbox/docname.html' from the editor's working SVN directory on the webserver).</p>
</li>
</ol>
</section2>
@ -270,14 +344,6 @@
<p>archive.sh</p>
<p>This script archives the version of a XEP currently on the website. Run this script before publishing a new version!</p>
</li>
<li>
<p>gen.sh</p>
<p>This script converts one XEP 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 &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>
</ol>
</section2>