XEP-README: XEP Editor README

Abstract:This document describes work processes followed by the XMPP Extensions Editor.
Author:Peter Saint-Andre
Copyright:© 1999 - 2016 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Experimental
Type:Procedural
Version:0.3
Last Updated:2015-07-12

NOTICE: This Procedural document proposes that the process or activity defined herein shall be followed by the XMPP Standards Foundation (XSF). However, this process or activity has not yet been approved by the XMPP Council and/or the XSF Board of Directors and is therefore not currently in force.


Table of Contents


1. Overview
2. XEP Editor Responsibilities
    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
    2.8. Deprecating a XEP
    2.9. Obsoleting a XEP
    2.10. XEP Maintenance
    2.11. List Administration
3. XMPP Registrar Responsibilities
    3.1. Advancing a XEP
    3.2. Creating a New Registry
    3.3. Updating an Existing Registry
4. Tools
    4.1. XML Processing
    4.2. XSL Transformations
    4.3. Entity References
    4.4. Python Scripts
    4.5. Shell Scripts

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History


1. Overview

The XMPP Extensions Editor (or, for short, XEP Editor) manages the XMPP extensions process as defined in XMPP Extension Protocols (XEP-0001) [1]. In addition, the XEP Editor functions as the XMPP Registrar as defined in XMPP Registrar Function (XEP-0053) [2]. Read those documents first, since this README focuses on mechanics instead of philosophy or policy.

Since the inception of the XMPP Standards Foundation (XSF) [3] in 2001 until early 2014, the XMPP Extensions Editor [4] was Peter Saint-Andre. In early 2014, the XMPP Standards Foundation (XSF) [5] 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.

2. XEP Editor Responsibilities

There are several XEP-related functions performed by the XEP Editor:

  1. Accepting a XEP
  2. Updating a XEP
  3. Deferring a XEP
  4. Retracting a XEP
  5. Issuing a Last Call
  6. Counting Council Votes
  7. Advancing a XEP
  8. Deprecating a XEP
  9. Obsoleting a XEP
  10. XEP Maintenance
  11. List Administration

These functions are specified below.

2.1 Accepting a XEP

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

  1. Receive proposal from authors.
  2. 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 https://xmpp.org/about/xsf/ipr-policy.
  3. Give it a descriptive filename that does not include the string 'xep' or a XEP number.
  4. Set the version to 0.0.1.
  5. Set the status to ProtoXEP.
  6. Locally convert XML to HTML and check the results for accuracy in accordance with normal XEP formatting (see Guidelines for Authors of XMPP Extension Protocols (XEP-0143) [6]).
  7. Check the XML file into the main branch of the XEP repository in the inbox/ subdirectory and then push the changes.
  8. Log into the webserver, change directories to /home/xsf/xmpp-hg/extensions, perform an hg pull && hg update, copy the protoxep file from the inbox/ subdirectory to the extensions/ directory, type 'xsltproc protoxepfile.xml > /var/www/vhosts/xmpp.org/extensions/inbox/protoxepfile.html', and remove the file from the extensions/ directory.
  9. Run "inxep.py name approvingbody" script on the webserver (eg. "./inxep.py pars council"; see note about List Administration).
  10. 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).
  11. If rejected, retain the XML file in git and the HTML file in the "inbox".
  12. 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 and the initials to "XEP Editor (psa)" where "psa" would be changed to your personal initials.
    4. Remove the <interim/> element from the XML file if it's included
    5. Set the status to Experimental.
    6. Check the file for egregious errors.
    7. Add a reference for the new XEP in the xep.ent file and check those changes into source control.
    8. 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.
    9. Run the "archive.sh" script, which copies this published version to http://xmpp.org/extensions/attic/.
    10. Run the "announce.py" script (see note about List Administration).
    11. Redirect the HTML file in the "inbox" to the new XEP URL (see existing examples on the webserver).

2.2 Updating a XEP

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.

  1. Verify that the version number, status, and other information are correct.
  2. Compile the file locally and check the content for accuracy (including the correct date and version number).
  3. Check the changes into source control.
  4. Log into the webserver as the 'xsf' user, 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.
  5. Run the "announce.py" script on the webserver (see note about List Administration).

For example, to update XEP-0353 from version 0.1 to 0.2, you might do something like the following:

$ sudo -u xsf -i
$ cd ~xsf/xmpp-hg/extensions
$ . /usr/local/virtualenv/gen/activate
$ # or "export PATH=/usr/local/virtualenv/gen/bin:$PATH
$ ./archive.sh 0353 0.1
$ hg pull && hg update
$ ./gen.py xep-0353.xml
$ ./announce.py 0353 http://xmpp.org/extensions/diff/api/xep/0353/diff/0.1/vs/0.2

2.3 Deferring a XEP

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.

  1. Change the <status/> element to "Deferred" in the XML file.
  2. Check your changes into source control (note: do not modify the version number!).
  3. Run the "gen.py" script on the webserver.
  4. 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.
  5. Run the "archive.sh" script, which copies this published version to http://xmpp.org/extensions/attic/.
  6. Run the "deferred.py" script on the webserver (see note about List Administration).

2.4 Retracting a XEP

Sometimes an author retracts a XEP because it is no longer deemed 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 source control.
  5. 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.
  6. Run the "announce.py" script on the webserver (see note about List Administration).

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 14 days in the future (sometimes 3 weeks if a great deal of discussion is expected).
  3. Change the <status/> element to "Proposed" in the XML file.
  4. Check your changes into source control.
  5. 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.
  6. Run the "lastcall.py" script on the webserver.
  7. 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. Monitor the Council list and Council meeting minutes for votes.
  2. Log into the website and modify the vote tally page linked to from <http://xmpp.org/about-xmpp/xsf/xmpp-council/>.
  3. 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; 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).
  3. Remove the <interim/> element from the XML file if it's included
  4. 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.
  5. 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).
  6. Check your changes into source control.
  7. 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.
  8. Run the "announce.py" script on the webserver (see note about List Administration).
  9. Update the protocol pages at http://xmpp.org/protocols/ to reflect advancement of the XEP.

2.8 Deprecating a XEP

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:

  1. 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.
  2. Change the <status/> element to "Deprecated" in the XML file.
  3. If instructed to do so by the Council, add an <expires/> element to the header.
  4. Add a <spec/> child to the <supersededby/> element, pointing to the specification that supersedes this one.
  5. Add a pointer to the superseding spec in the abstract and a new first paragraph of the XEP (see existing examples).
  6. Check your changes into source control.
  7. 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.
  8. Run the "announce.py" script on the webserver (see note about List Administration).

2.9 Obsoleting a XEP

The Council can decide to change the status of a XEP from Deprecated to Obsolete. Here is the process:

  1. 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.
  2. Change the <status/> element to "Obsolete" in the XML file.
  3. If the file includes an <expires/> element in the header, remove it.
  4. If appropriate, add a <spec/> child to the <supersededby/> element, pointing to the specification that supersedes this one.
  5. If appropriate, add a pointer to the superseding spec in the abstract and a new first paragraph of the XEP.
  6. Check your changes into source control.
  7. 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.
  8. Run the "announce.py" script on the webserver (see note about List Administration).

2.10 XEP Maintenance

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

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 XEP-0001 for details.

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 XEP-0143. Such work is best done while a XEP is still Experimental.

2.11 List Administration

XEPs are discussed on the standards@xmpp.org email list, about which information is available at <http://mail.jabber.org/mailman/listinfo/standards>. 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.

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.

3. XMPP Registrar Responsibilities

3.1 Advancing a XEP

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

3.2 Creating a New Registry

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

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.

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.

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

3.3 Updating an Existing Registry

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.

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.

4. Tools

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

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 sending a message to standards@xmpp.org (see note about List Administration).

  2. deferred.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.py shell script.

  3. gen.py

    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.

  4. lastcall.py

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

  5. 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://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).

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 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!

  2. archive.sh

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


Appendices


Appendix A: Document Information

Series: XEP
Number: README
Publisher: XMPP Standards Foundation
Status: Experimental
Type: Procedural
Version: 0.3
Last Updated: 2015-07-12
Approving Body: XMPP Council
Dependencies: XEP-0001, XEP-0053
Supersedes: None
Superseded By: None
Short Name: N/A
Source Control: HTML
This document in other formats: XML  PDF


Appendix B: Author Information

Peter Saint-Andre

Email: peter@andyet.net
JabberID: stpeter@stpeter.im
URI: https://stpeter.im/


Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2016 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <http://xmpp.org/about-xmpp/xsf/xsf-ipr-policy/> or obtained by writing to XMPP Standards Foundation, 1899 Wynkoop Street, Suite 600, Denver, CO 80202 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.


Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata can be sent to <editor@xmpp.org>.


Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".


Appendix G: Notes

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

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

3. 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://xmpp.org/xsf/>.

4. 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://xmpp.org/about-xmpp/xsf/xsf-people/#editor>.

5. 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://xmpp.org/xsf/>.

6. XEP-0143: Guidelines for Authors of XMPP Extension Protocols <http://xmpp.org/extensions/xep-0143.html>.


Appendix H: Revision History

Note: Older versions of this specification might be available at http://xmpp.org/extensions/attic/

Version 0.3 (2015-07-12)

Update the accepting an XEP section.

(ssw)

Version 0.2 (2016-05-16)

Make the updating an XEP section match current process.

(ssw)

Version 0.10 (2016-01-21)

Added reminders to remove <interim> elements.

(asw)

Version 0.9 (2014-02-25)

Modernized to reflect updated scripts and processes, as well as the existence of the XSF's Editor Team.

(psa)

Version 0.8 (2009-11-19)

Updated to reflect newer processes and provide more complete coverage of XEP Editor and XMPP Registrar responsibilities.

(psa)

Version 0.7 (2008-07-16)

Updated to reflect use of SVN.

(psa)

Version 0.6 (2007-09-28)

Updated to reflect new scripts and use of mailserver.

(psa)

Version 0.5 (2005-05-26)

Adjusted to reflect ProtoXEP status.

(psa)

Version 0.4 (2005-03-16)

Converted to XEP format; adjusted to reflect server move.

(psa)

Version 0.3 (2004-10-22)

Clarified schema handling.

(psa)

Version 0.2 (2004-10-11)

Defined XMPP Registrar processes.

(psa)

Version 0.1 (2004-10-01)

Initial version.

(psa)

END