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

0.9

This commit is contained in:
Peter Saint-Andre 2014-02-25 11:38:13 -07:00
parent 59723fa0cd
commit 3196467b12
1 changed files with 54 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
xep-README.xml
View File

@ -22,6 +22,12 @@
<supersededby/>
<shortname>N/A</shortname>
&stpeter;
<revision>
<version>0.9</version>
<date>2014-02-25</date>
<initials>psa</initials>
<remark><p>Modernized to reflect updated scripts and processes, as well as the existence of the XSF's Editor Team.</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2009-11-19</date>
@ -73,8 +79,8 @@
</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 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>
<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 or policy.</p>
<p>Since the inception of the &XSF; in 2001 until early 2014, the &EDITOR; was Peter Saint-Andre. In early 2014, the &XSF; formed a "work team" to dispatch the responsibilities of the XEP Editor and XMPP Registrar. This document describes most of the details about how those responsibilities are performed.</p>
</section1>
<section1 topic='XEP Editor Responsibilities' anchor='ed'>
@ -91,7 +97,6 @@
<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>
@ -101,71 +106,63 @@
<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 revision block is found.</li>
<li>Set the version to 0.0.1.</li>
<li>Set the status to ProtoXEP.</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>Locally convert XML to HTML and check the results for accuracy in accordance with normal XEP formatting (see &xep0143;).</li>
<li>Check the XML file into the main branch of the XSF's git repository in the inbox/ subdirectory under extensions/ and then push the changes.</li>
<li>Log into the webserver, change directories to /home/xsf/git, perform a git pull, copy the protoxep file from the inbox/ subdirectory to the extensions/ directory, type 'xsltproc protoxepfile.xml &gt; /var/www/vhosts/xmpp.org/extensions/inbox/protoxepfile.html', and remove the file from the extensions/ directory.</li>
<li>Run the "inxep.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</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>If rejected, retain the XML file in git and the HTML file in the "inbox".</li>
<li>
<p>If accepted, do the following:</p>
<ol>
<li>Assign the XEP the next available number in the XEP 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 version to 0.1 and the initials to "XEP Editor (psa)" where "psa" would be changed to your personal initials.</li>
<li>Set the status to Experimental.</li>
<li>Check the file for egregious errors.</li>
<li>Add the XML file to the 'extensions' directory in the "xmpp" SVN module.</li>
<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.py" script on the webserver.</li>
<li>Add a reference for the new XEP in the xep.ent file and check those changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</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>
<li>Run the "announce.py" script (see note about <link url='#lists'>List Administration</link>).</li>
<li>Redirect the HTML file in the "inbox" to the new XEP URL (see existing examples on the webserver).</li>
</ol>
</li>
</ol>
</section2>
<section2 topic='Updating a XEP' anchor='updating'>
<p>Once a XEP has been published, it will be periodically updated in SVN, 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 source control, 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 or when the status is changing from, say, Deprecated to Obsolete). Here is how to update a XEP.</p>
<ol>
<li>Verify that the version number, status, and other information are correct.</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 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.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>Check the changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
<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 12 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 submitted in 12 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>
<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>Check your changes into source control (note: do not modify the version number!).</li>
<li>Run the "gen.py" script on the webserver.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</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>
<li>Run the "deferred.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
<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 deemed 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 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 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.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>Check your changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
@ -174,12 +171,10 @@
<p>The XMPP Council determines whether and when to issue a Last Call on an Experimental XEP. 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>Determine the ending date, which must be at least 14 days in the future (sometimes 3 weeks if a great deal of discussion is expected).</li>
<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.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>Check your changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</li>
<li>Run the "lastcall.py" script on the webserver.</li>
<li>Review the XMPP Registrar Considerations section to ensure accuracy.</li>
</ol>
@ -188,12 +183,8 @@
<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 or chatroom logs).</li>
<li>Monitor the Council list and Council meetings for votes.</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.py script).</li>
<li>Monitor the Council list and Council meeting minutes for votes.</li>
<li>Log into the website and modify the vote tally page linked to from &lt;<link url='http://xmpp.org/about-xmpp/xsf/xmpp-council/'>http://xmpp.org/about-xmpp/xsf/xmpp-council/</link>&gt;.</li>
<li>When all Council members have voted, update the XEP accordingly (see below on Advancing a XEP).</li>
</ol>
</section2>
@ -202,7 +193,7 @@
<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>
<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 XEPs for appropriate remarks).</li>
<li>Add a new revision block; set the version number to "1.0" and the initials to "XEP Editor (psa)" where "psa" would be changed to your personal initials (see existing XEPs for appropriate remarks).</li>
<li>If there are any XML schemas associated with the XEP, do the following:
<ol>
<li>Add an annotation to each schema (see existing examples).</li>
@ -211,9 +202,8 @@
</ol>
</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>Update SVN on the webserver.</li>
<li>Run the "gen.py" script.</li>
<li>Check your changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</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>
@ -222,32 +212,28 @@
<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>Add a new revision block; increment the version number and set the initials to "XEP Editor (psa)" where "psa" would be changed to your personal initials.</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>
<li>Add a pointer to the superseding spec in the abstract and a new first paragraph of the XEP (see existing examples).</li>
<li>Check your changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</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>Add a new revision block; increment the version number and set the initials to "XEP Editor (psa)" where "psa" would be changed to your personal initials.</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>
<li>Check your changes into source control.</li>
<li>Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, run the "archive.sh" script to copy the previous XEP version to the "attic" (just in case the last editor team member forgot), type 'hg pull' and 'hg update', and run the "gen.py" script to generate HTML and PDF files.</li>
<li>Run the "announce.py" script on the webserver (see note about <link url='#lists'>List Administration</link>).</li>
</ol>
</section2>
@ -258,18 +244,8 @@
</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>
<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 acted 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>
<p>With the transition to the XSF Editor Team, the editor@xmpp.org address is also an email list, used by the team. Incoming messages need to be screened for legitimacy and approved as appropriate.</p>
</section2>
</section1>
@ -283,12 +259,13 @@
<section2 topic='Creating a New Registry' anchor='reg-newreg'>
<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>
<p class='note'>Note: Registry entries are often a source of confusion and error. It is recommended for several members of the XSF Editor Team to review registry changes before pushing them to the website.</p>
<p>Check all your changes into source control, update the registrar/ directory from source 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>
<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 the 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>
@ -320,7 +297,7 @@
</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>
<p>This script converts one XEP XML file into HTML and PDF, 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>
@ -338,7 +315,7 @@
<ol>
<li>
<p>all.sh</p>
<p>This script converts all XEP XML files into HTML. Use this if the xep.xsl file changes in ways that affect all XEPs. But make sure that SVN is synced up first -- you don't want to be publishing interim versions of XEPs!</p>
<p>This script converts all XEP XML files into HTML and PDF. Use this if the xep.xsl file changes in ways that affect all XEPs. But make sure that SVN is synced up first -- you don't want to be publishing interim versions of XEPs!</p>
</li>
<li>
<p>archive.sh</p>