XEP-0143

2013年5月6日 (一) 04:09的版本

本文的英文原文来自XEP-0143

XEP-0143: XMPP扩展协议作者指南

注意: 这个程序文档定义了一个已经被XMPP委员会和/或XSF董事会批准的XMPP标准基金会(XSF)的流程或活动. XSF目前正是遵循这里定义的流程或活动并且将继续这么做，直到本文档被取消或废除.

简介

XMPP标准基金会(XSF) 1 收到大量的提案为XMPP Core 2中定义的核心XMPP协议定义扩展. 然而, 作者们并不总是清楚怎样最佳地结构化一个提案以让它能作为一个XMPP扩展(XEP)被接受并从而进一步通过XSF的标准流程. 所以, 本文提供指南来帮助作者写出更好的XMPP扩展协议定义.

这些指南假定读者们对XMPP扩展协议 3所定义的XEP系列文档和XSF处理它们的流程很熟悉, .

提交提案之前

强烈鼓励一个可能的作者在提交一个提案成为一个XEP之前完成一些研究. 特别是, 该作者应该做以下几件事:

• 查看XMPP RFCs和实验性的, 活跃的, 草案, 和最终XEPs以决定是否真的为了填补现有的XMPP技术和协议的空白而需要该建议的协议扩展.
• 查看被拒绝的和被延期的XEPs, 以及那些永远不会被接受的提案(见 <http://xmpp.org/extensions/inbox/>)来决定是否过去已经有类似的扩展提案但是没有被XMPP理事会 4 批准.
• 查看其他标准开发组织开发的协议, 例如互联网工程工作组(IETF) 5和万维网联盟(W3C) 6, 来决定是否它们比在一个新的XMPP扩展里更合适.
• 查看Standards SIG 7中的讨论以决定是否过去已经讨论过或目前正在讨论类似的功能.

在完成这些研究之后, 潜在的作者可以断定是否需要新的协议扩展. 如果需要, 强烈建议该作者做以下事情:

1. 查看 XEP-0001 和 XMPP设计准则 8.
2. 理解提交过程.
3. 熟悉XEP的XML格式.
4. 然后只写一个提案包含所有适当的XEP章节.
5. 查看内容并确保它遵循XEP Styleguide.

提交提案

提交一个提案成为XEP的过程很简单:

1. 联系XMPP Extensions Editor 9 让他知道等待你的提案.
2. 遵循本文描述的指南写下你的提案.
3. 确保你在提交你的提案之前阅读, 理解, 并同意XSF IPR Policy 10.
4. 把你的XML文件(或一个指向该文件的URL)发给XMPP扩展编辑.

维护XEP

如果你的提案被接受成为一个XEP, 你可能需要定期更新这个协议以整合反馈以及实现和部署的经验. XMPP扩展编辑将分配一个号码给你的文档并添加到源文件控制中.

XMPP扩展编辑比较喜欢你按以下步骤工作:

1. 遵循<http://xmpp.org/about-xmpp/xsf/xsf-source-control/> 的指引从XSF的git仓库检出一份拷贝
2. 对文档做出你期望的修改, 包括一个如下所属的新 <revision/> 元素.
3. 使用命令 git format-patch HEAD^生成一个补丁
4. 使用命令 git send-email --to=editor@xmpp.org NAMEOF.patch发送该补丁

XMPP扩展编辑将应用你的补丁并发布一个你的XEP的更新版本.

注意: 如XEP-0001解释的一样, 实验状态的XEPs的更新版本的发布不需要XMPP理事会的批准. 无论如何, 活跃,草案,或最终状态的XEPs的更新版本必须由XMPP理事会批准以确保对于已批准的协议的正确的变更控制.

XEP的XML格式

XEP的XML格式实质上类似于XHTML的精简集. 这是有意的: 这使XEPs作者更易使用. 实际上, 如果你使用模版文件以及和它相关的XSLT样式表, 你应该能够在大多数现代浏览器中查看你的提案(见下文). 以下章节解释了如何开始XEP的写作并描述了用于XEPs的XML格式(正式的描述参见 xep.xsd 或 xep.dtd 文件).

和XEP文件一起工作

在你的提案上开始工作的最好的办法是从源文件控制获取所有现有的XEP文件和相关的样式表. 这些文件使用git存储，如 <http://xmpp.org/about-xmpp/xsf/xsf-source-control/> 所述. 文档结构同时被DTD和XML schema正式地定义, 但是你不需要为了写一个XEP而理解正规的描述. 此外, 在 'extensions' 目录有一个方便的模版文件 'xep-template.xml' , 提供了XEP写作的快速起点.

为了创建你的提案, 做一次'xmpp' 模块的 git checkout , 变更目录到 'extensions/' 目录, 拷贝模板文件 (例如, 'cp xep-template.xml xep-foo.xml'), 然后开始使用基本编辑器或专业的XML编辑器应用例如 XML Spy 或 XMLmind来编辑文件.

即使你使用一个基本的编辑器, 你也应该能在大多数现代的web浏览器上以XML文件方式查看你的文档，只要在'extensions/'目录有xep.xsl和xep.dtd文件 . 因为浏览器中的XSLT实现不一致, 特定的格式(例如, 表布局和表编号, 示例, 以及脚注)可能不完美. 不用着急; 它在XMPP扩展编辑制作的HTML输出中会看起来不错. 如果你的XML文件根本不能展现(即, 它只是一个大的文本块), 表明你使用的是一个坏的浏览器. 如果你只看到xep.xsl生成的很少几行而没有看到你的文本, 表明你的XML有错误. 你可以 xml.com 11检查你的XML语法在.

要用程序来把你的XML文件转成HTML, 我们推荐使用Daniel Veillard的xsltproc]程序, 它会给出一些关于XML语法问题的有用的错误信息. 无论如何, XMPP扩展编辑将完成最终的把XML转成HTML以及把你的HTML文件投递到 www.xmpp.org, 所以你不需要为了提交个哦XMPP扩展编辑而生成HTML文件(实际上, XMPP扩展编辑要求你以XEP XML格式而不是HTML格式提交提案).

最后, xep.ent 文件包含了方便的 "外部实体" 来提供快捷方式去包含对XMPP扩展协议, RFCs, 和其他通用字符串的参考. 不幸的是, 大部分浏览器不能正确地处理外部实体, 所以如果你需要在一个浏览器中查看你的XML源文件，那么你不能从xep.ent包含实体. 无论如何, XMPP扩展编辑保留把你的标记转换成外部实体的权力, 因为这使他的工作容易一些. 而且, 请不要添加条目到 xep.ent 文件; 反之, 把它们作为inline实体添加到你的文档中然后请XMPP扩展编辑把它们添加到 xep.ent 文件.

文件元数据

本章描述包含在XEP文件的<header/>元素中的元数据元素(文件内容请见下文).

<title/>元素的XML字符串数据是你的XEP的标题. 选择一个少于十个单词长度的描述性标题. XMPP扩展编辑可能在和作者讨论后修改它.

<abstract/>元素的XML字符串数据应该是一个或两个句子关于你的提案的摘要(通常开始于"本协议定义了一个XMPP协议扩展..."). XMPP扩展编辑将会修改这个摘要以使它准确地描述该提案.

<legal/>元素的XML字符串数据必须如 XSF IPR Policy 中那样定义并且同时反映在xep.ent文件和XEP模板中.

<number/>元素的XML字符串数据应该是"xxxx"; 如果XMPP理事会接受该提案成为一个XMPP扩展协议，它将由XMPP扩展编辑修改成下一个顺序的XEP编号.

<status/>元素的XML字符串数据应该是"ProtoXEP"，因为所有提案开始都是"proto-XEPs"; 如果XMPP理事会接受该提案成为一个XMPP扩展协议，它将被改为"Experimental".

<type/>元素的XML字符串数据应该要么是"Standards Track"要么是"Informational" (也有 Historical, Humorous, 和 Procedural XEPs, 但是那些是不通用并且常见是由XMPP扩展编辑写的). 一个Standards Track XEP 定义一个打算用作XMPP技术的通用部分的XMPP扩展. 一个Informational XEP 定义最佳实践或一个和XMPP或XMPP扩展协议相关的范本的使用(例如, Best Practices for Use of SASL ANONYMOUS 12).

<approver/>元素的XML字符串数据应该是"Council".

<dependencies/>元素用于以一个规范性的方法定义你的提案所依赖的RFCs, XMPP扩展协议, 和其他协议(即, 为了实现你提议的协议，这些协议必须或应该被理解). 每个协议必须由一个唯一的<spec/>子元素来标识(关于文档标识符的线索请参考现有的XEP协议, 或询问XMPP扩展编辑).

<supersedes/>, <supersededby/>, <shortname/>, 和<schemaloc/>元素由XMPP扩展编辑使用; 无论如何, 如果你的文档取代一个现有的XMPP扩展协议, 可以把要取代的那个协议包含在一个定义该文档标识符的<spec/>子元素中(例如, XEP-0093).

为每一个合著者包含一个<author/>元素. 注意，根据XEP-0001的要求<firstname/>和<surname/>元素是必需的, 然后是一些<email/>, <jid/>, 和<uri/>元素的组合， 这样就有了适当的可用的联系人信息.

为你的文档的每一个修订包含一个<revision/>元素.你给XMPP编辑的初始提交文档的<version/>元素的XML字符串数据应该是"0.0.1", 并且<remark/>元素应该是"First draft."; 对每一个修订, 你将包含一个新的<revision/>元素(把它放在现有的<revision/>元素的前面)并且重复<version/>元素(例如, "0.0.2"在"0.0.1"后面或"0.10"在"0.9"后面). <date/>元素的格式为 yyyy-mm-dd.

文件内容

除了<header/>元素（见上文）里的元数据，XEP文件是一系列的章节，以层次结构来排版（<section1/>是一个顶层章节，您可以在其中嵌套<section2/>章
 
节，一直到<section4/>）。一个章节的标题是其“topic”属性。你也应该包括一个'anchor'属性，让您可以在您的文档链接到页面中的片段。章节元素内允许
 
的元素可能看起来类似XHTML：<p/>为段落，<ol/>和<ul/>为有序和无序列表，依此类推。
 
<example/>和<code/>元素是用来显示协议片段; <example/>元素应具备“caption”属性以描述示例，而<code/>元素没有这个属性。在这些元素内都定义
 
了一个XML CDATA章节，这样你就不需要在你的示例XML节中避免“<”和“>”字符，因为这使作者和编辑的生活变得更容易（见现有XEP协议的标记）。
 
<p​​/>和<li/>元素，也可以包含多个标记，来自熟悉的XHTML，如<img/>元素。注意超链接的形式是<link url='foo'>bar</link>，而不是
 
<a href='foo'>bar</a>的（其中的原因已经迷失在时间的迷雾中，而且现在更改它已经太晚了，所以你不得不调整）。如果需要，您还可以在<P/>合<li/>元
 
素内使用内嵌结构和表象的标记，如<em/>，<strong/>，<tt/>，<cite/> <span/>。
 
您可能还包括了表（这些都是有利于罗列错误代码等）。 <table/>元素应具备的“caption属性说明表的内容。标准的XHTML表结构适用（<tr/>定义一行，其
 
中包含标题行的<th/>元素和数据行的<td/>元素），而“colspan'和'rowspan的属性也可以用，如果需要他们的话。表格展现由XSLT和CSS样式表
 
（如cellpadding和cellspacing）处理。但是记住，这并不意味着表是用来显示了大量文本的。
 
xep.xsl文件执行各种魔法，在XML文件转换成HTML，包括前面的问题创建，表的内容，章节编号，备注，和修订历史记录。请随意对此文件提交补丁，但不要向源
 
代码控制提交修改后的版本。
 
虽然HTML是XEPs的主要发行格式，自2009年以来XMPP扩展编辑也发布XEPs的PDF文件的形式。牢记这一点，尽量避免表中的列太多，这可能需要比正常更宽的纸张。

XEP文档的章节

大部分XEP协议有以下大部分章节, 经常以下面所述的顺序排列. 其他章节可以是适当的(例如, XHTML-IM 13 有一个章节是讲W3C事项). 关于为了阐述你的论据而需要的章节你要使用你自己的最佳判断, 或针对你的需要咨询XMPP扩展编辑.

简介

一个XEP文档的简介是非常重要的，因为它提供了考虑的提案的基本原理. 特别是, 简介应该包含类似如下信息:

1. 因为缺少你提议的协议而使用户现在不能完成的任务. (注意: 用户不只是IM用户, 而可以是任何人, 系统, 或可以通过XMPP网络和其他实体交互而带来价值的应用.)
2. 其他项目或协议以及XMPP技术如何因为你提议的协议而与它们交互(例如, XML-RPC, SOAP).
3. XMPP技术和"竞争者"之间的比较(例如, 其他IM系统或消息协议)，描述为了提供类似功能XMPP协议簇中需要填补的空白.
4. XMPP社区中思考的相关历史.
5. 真实世界中该协议能解决的问题的例子.

需求

每个XEP文档应该包含一个章节来描述该文档所代表的需求. 这个信息是关键和重要的, 因为它清楚地定义本提案的范围以及在协议设计上的任何相关的约束.

词汇表

如果你的XEP文档使用读者不熟悉的术语, 请在一个词汇表中定义它们.

推荐的词汇表的布局是一个定义列表，使用HTML的

标签(示例见现有的XEPs).

用例

建议文档作者根据提案将要阐述的用例来结构化他们的提案. 14 我们发现用例强迫作者专注于功能而不是"为了协议而做协议". 它也有助于根据参与者来排列用例, 比如在 Multi-User Chat 15 中就是这样做的. 每个用例包含一个子章节.

写用例和相关协议的时候, 确保以下要点:

• 清晰地定义成功场景, 候补流程, 和可能的错误.
• 描述使用本协议的时候XMPP客户端,服务器,和外部组件的预期行为.
• 包含很多协议示例. 16

我们重申: 包含很多协议示例. 示例不仅帮助实现者而且也帮助那些在标准SIG和XMPP理事会中审核你的提案的人. 如果你遵循Jabber传统使用莎士比亚戏剧中的角色和情景，你将得到XMPP扩展编辑的额外信任:

示例1. 一个来自莎士比亚的例子

<message 
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'
    type='chat'>
  <body>Wherefore art thou, Romeo?</body>
</message>

错误代码

如果你的提案定义了一些错误和状态码(如XEP-0045中做的那样), 包含一个你文档中定义的所有代码的表格是个好主意.

商业规则

你可能希望包含一个章节来描述各种商业规则(基本上, 是关于应用行为的 MUSTs, SHOULDs, 和 MAYs 的变种). 这不是必需的但有助于实现者.

实现备注

你可能希望包含一个实现备注章节. 同样, 这不是必需的但是有助于实现者.

国际化事项

如果有任何和你的提案相关的国际化或本地化的问题(例如, 是否包含'xml:lang'属性), 在这个可选的章节定义它们.

安全事项

你的提案必须包含一个"安全事项"的章节. 即使没有和你的提案相关的安全特性或关系, 你也必需标注那种情况. 有益的指南请参考RFC 3552 17; 核心XMPP协议(RFC 6120) 也包含非常全面的安全事项章节，可作为范例来参考.

IANA事项

本章是必需的. IANA即互联网号码分配机构(IANA) [XEP-0143#附录G:备注|18]], 互联网协议的唯一性参数值分配的核心协调者, 例如号码和URI schemes. 大部分提案不要求和IANA的互动, 这种情况下本章的文本应为"本文不需要和互联网号码分配机构(IANA)交互." 如果你的提案要求和IANA交互, 和XMPP扩展编辑的XMPP注册处讨论这件事. 不要自己直接联系IANA!

XMPP注册处事项

XML Schema

===致谢===