XEP-README: XEP Editor README

Peter Saint-Andre

JabberID: stpeter@jabber.org
URI: https://stpeter.im/

Copyright

Permissions

Disclaimer of Warranty

Limitation of Liability

IPR Conformance

1. Overview
2. XEP Editor Processes
    2.1. Accepting a XEP
    2.2. Updating a XEP
    2.3. Deferring a XEP
    2.4. Retracting a XEP
    2.5. Issuing a Last Call
    2.6. Counting Council Votes
    2.7. Advancing a XEP
3. XMPP Registrar Processes
    3.1. Advancing a XEP
    3.2. Creating a New Registry
4. Tools
    4.1. XML Processing
    4.2. XSL Transformations
    4.3. Entity References
    4.4. Python Scripts
    4.5. Shell Scripts
Notes
Revision History

2.1 Accepting a XEP

Periodically, people send email to editor@xmpp.org with new proposals. Here is how to process such submissions.

1. Receive proposal from author.
2. Give it a descriptive filename that does not include the string 'xep' or a XEP number.
3. Set the version to 0.0.1 if no version found.
4. Set the status to ProtoXEP.
5. Convert XML to HTML and check the results for accuracy.
6. Place HTML at http://www.xmpp.org/extensions/inbox/ (/var/www/xmpp.org/extensions/inbox/ on the webserver)
7. Place XML in the editor's working Subversion directory on the webserver (e.g., ~/svn/xmpp/extensions/docname.xml)
8. Send a note to the Standards list by running the "inxep.py" script.
9. Wait until the Council decides whether to accept the proposal as a XEP (this may involve poking the Council Chair).
10. If rejected, retain in the "inbox".

11. If accepted, do the following:

    1. Assign the XEP the next available number in the XEP series.
    2. Modify the <number/> element in the XML file.
    3. Set the version to 0.1.
    4. Set the status to Experimental.
    5. Check the file for egregious errors.
    6. Add the XML file to the 'extensions' directory in the "xmpp" SVN module.
    7. Add the file to the SVN repository.
    8. Add a reference for the new XEP in the xep.ent file and check those changes into SVN.
    9. Update SVN on the webserver.
    10. Run the "gen.sh" script on the webserver.
    11. Run the "dbupdate.py" script on the webserver.
    12. Run the "announce.py" script on the webserver.
    13. Redirect the "inbox" file to the new XEP URL.

2.2 Updating a XEP

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.

1. Compile the file locally and check the content for accuracy (including the correct date and version number).
2. Check your changes into SVN.
3. Run the "archive.sh" script to put the previous XEP version in the "attic".
4. Update SVN on the webserver.
5. Run the "gen.sh" script on the webserver.
6. Run the "dbupdate.py" script on the webserver.
7. Run the "announce.py" script on the webserver.

2.3 Deferring a XEP

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.

1. Change the <status/> element to "Deferred" in the XML file.
2. Check your changes into SVN (note: do not modify the version number!).
3. Update SVN on the webserver.
4. Run the "gen.sh" script on the webserver.
5. Run the "deferred.py" script on the webserver.

2.4 Retracting a XEP

Sometimes an author retracts a XEP because it is no longer worthy of consideration. Here is the process.

1. Change the <status/> element to "Retracted" in the XML file.
2. Modify the <abstract/> element with appropriate content (see existing Retracted XEPs).
3. Add a new revision block with an incremented version number, explaining that the XEP has been Retracted and why (see existing Retracted XEPs).
4. Check your changes into SVN.
5. Run the "archive.sh" script to put the previous XEP version in the "attic".
6. Update SVN on the webserver.
7. Run the "gen.sh" script on the webserver.
8. Run the "dbupdate.py" script on the webserver.
9. Run the "announce.py" script on the webserver.

2.5 Issuing a Last Call

The XMPP Council determines whether and when to issue a Last Call on an Experimental XEP. Here is the process.

1. Receive notice from the Council Chair that a Last Call shall be issued.
2. 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).
3. Change the <status/> element to "Proposed" in the XML file.
4. Check your changes into SVN.
5. Update SVN on the webserver.
6. Run the "gen.sh" script on the webserver.
7. Run the "dbupdate.py" script on the webserver.
8. Run the "lastcall.py" script on the webserver.
9. Review the XMPP Registrar Considerations section to ensure accuracy.

2.6 Counting Council Votes

The XEP Editor is responsible for counting the votes of Council members. The process is as follows.

1. Inform the Council of the vote (see examples in the council@xmpp.org mailing list archives).
2. Monitor the Council list and Council meetings for votes.
3. Update the appropriate Council tally file in the 'council' directory.
4. Check your changes into SVN.
5. Update SVN on the server.
6. Run the "gen.sh" script in the 'council' directory (don't confuse this with the XEP gen.sh script).
7. When all Council members have voted, update the XEP accordingly (see below on Advancing a XEP).

2.7 Advancing a XEP

When the Council approves a XEP, it advances to either Draft (Standards Track XEPs) or Active (other XEP types). Here is the process.

1. Change the <status/> element to "Active" or "Draft" as appropriate.
2. Add a new revision block with a version number of "1.0" (see existing XEPs for appropriate remarks).
3. If there are any XML schemas associated with the XEP, do the following:
   1. Add an annotation to each schema (see existing examples).
   2. In the 'schemas' directory, create one .xsd file for each schema.
   3. For each schema, add a <schemaloc/> element to the XEP file.
4. 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).
5. Check your changes into SVN.
6. Run the "archive.sh" script to put the previous XEP version in the "attic".
7. Update SVN on the webserver.
8. Run the "gen.sh" script.
9. Run the "dbupdate.py" script on the webserver.
10. Run the "announce.py" script on the webserver.

3.1 Advancing a XEP

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").

3.2 Creating a New Registry

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.)

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.

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.

4.1 XML Processing

In order to convert XML files into HTML and other formats, the XEP 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.

4.2 XSL Transformations

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.

4.3 Entity References

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.

4.4 Python Scripts

Several Python scripts are under source control. These are:

1. announce.py

   This script announces a new version of a XEP by updating the database and sending a message to standards@xmpp.org.

2. deferrred.py

   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 <status/> element in the XEP itself and run the gen.sh shell script.

3. lastcall.py

   This script announces a Last Call for a XEP by updating the database and sending a message to standards@xmpp.org.

4. protoxep.py

   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).

4.5 Shell Scripts

Several shell scripts are under source control. These are:

1. all.sh

   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!

2. archive.sh

   This script archives the version of a XEP currently on the website. Run this script before publishing a new version!

3. gen.sh

   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.

4. schemagen.sh

   This script updates all of the XML schemas located at <http://www.xmpp.org/schemas/>. Update this file every time a protocol XEP with an associated schema advances to Active or Draft.

1. The XMPP Standards Foundation (XSF) is an independent, non-profit membership organization that develops open extensions to the IETF's Extensible Messaging and Presence Protocol (XMPP). For further information, see <http://www.xmpp.org/xsf/>.

2. The XMPP Extensions Editor is the individual appointed by the XSF Board of Directors to handle protocol submissions and provide day-to-day management of the XSF's standards process. For further information, see <http://www.xmpp.org/extensions/editor.shtml>.

3. XEP-0001: XMPP Extension Protocols <http://www.xmpp.org/extensions/xep-0001.html>.

4. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.

Version 0.7 (2008-07-16)

Version 0.6 (2007-09-28)

Version 0.5 (2005-05-26)

Version 0.4 (2005-03-16)

Version 0.3 (2004-10-22)

Version 0.2 (2004-10-11)

Version 0.1 (2004-10-01)