概述
本文档描述了如何修改I2P规范、I2P提案的工作原理以及I2P提案与规范之间的关系。
本文档改编自Tor提案流程,下面的内容大部分最初由Nick Mathewson编写。
这是一个信息文档。
动机
以前,我们更新I2P规范的流程相对比较非正式:我们会在开发论坛上提出一个提案并讨论更改,然后我们会达成共识并用草稿更改修补规范(不一定按这个顺序),最后我们会实现这些更改。
这种做法有几个问题。
首先,即使在最有效的情况下,旧的流程也经常导致规范与代码不同步。最糟糕的情况是那些被延迟实现的:规范和代码可能会在版本之间保持不同步。
第二,参与讨论很困难,因为不总是清楚哪些部分的讨论线程属于提案,或者哪些规范更改已经被实现。开发论坛只能在I2P内部访问,这意味着提案只能被使用I2P的人查看。
第三,很容易忘记一些提案,因为它们会被埋在论坛线程列表的几页后面。
如何修改规范
现在,首先有人编写一个提案文档。它应该详细描述应该做出的更改,并给出一些关于如何实现它的想法。一旦它被充分阐述,就成为一个提案。
像RFC一样,每个提案都会得到一个编号。与RFC不同,提案可以随着时间的推移而更改并保留相同的编号,直到它们被最终接受或拒绝。每个提案的历史将存储在I2P网站仓库中。
一旦提案进入仓库,我们应该在相应的线程中讨论它并改进它,直到我们达成共识认为这是一个好主意,并且它的详细程度足以实现。当这种情况发生时,我们实现提案并将其纳入规范中。因此,规范仍然是I2P协议的规范文档:没有任何提案是已实现功能的规范文档。
(这个过程与Python增强流程非常相似,主要区别在于I2P提案在实现后会被重新集成到规范中,而PEP会成为新的规范。)
小更改
如果代码可以立即编写,或者如果不需要代码更改,则仍然可以直接对规范进行小更改。这份文档反映了当前开发人员的意图,而不是对未来始终使用此流程的永久承诺:我们保留在兴奋时运行并实现某些功能的权利,例如在咖啡因或M&M驱动的通宵编码会话中。
如何添加新提案
要提交提案,请在开发论坛上发布它或提交一个带有提案附件的票据。
一旦一个想法被提议,存在一个格式正确(见下文)的草稿,并且在活跃的开发社区中存在粗略的共识认为这个想法值得考虑,提案编辑器将正式添加提案。
当前的提案编辑器是zzz和str4d。
提案中应该包含什么
每个提案都应该有一个包含以下字段的标题:
:author:
:created:
:thread:
:lastupdated:
:status:
author字段应该包含提案的作者姓名。thread字段应该是开发论坛线程的链接,原始提案在那里被发布,或者是为讨论此提案而创建的新线程。lastupdated字段应该最初等于created字段,并且应该在每次提案更改时更新。
这些字段应该在必要时设置:
:supercedes:
:supercededby:
:editor:
supercedes字段是一个用逗号分隔的被此提案替换的所有提案列表。这些提案应该被拒绝,并且它们的supercededby字段应该设置为此提案的编号。editor字段应该设置,如果对提案进行了重大更改,但这些更改并没有实质性地改变其内容。如果内容正在被实质性地改变,应该添加一个额外的author,或者创建一个新的提案来替换这个提案。
这些字段是可选的,但建议使用:
:target:
:implementedin:
target字段应该描述提案希望在哪个版本中实现(如果它是开放或接受的)。implementedin字段应该描述提案在哪个版本中实现(如果它是完成或关闭的)。
提案的正文应该以概述部分开始,解释提案的内容、它的作用以及它的状态。
在概述之后,提案变得更加自由形式。根据其长度和复杂性,提案可以分成适当的部分,或者遵循简短的讨论格式。每个提案在被接受之前都应该至少包含以下信息,尽管这些信息不需要在具有这些名称的部分中。
动机 :提案试图解决什么问题?为什么这个问题很重要?如果有多种方法可以解决这个问题,为什么选择这种方法?
设计 :对新功能或修改功能的高层次概述,包括它们如何工作、如何相互操作以及如何与I2P的其他部分交互。这是提案的主要内容。一些提案可能一开始只有动机和设计,并且在设计看起来大致正确之前等待规范。
安全影响 :提议的更改可能对匿名性产生什么影响,这些影响有多好地被理解,以及其他问题。
规范 :对需要添加到I2P规范中的内容的详细描述,以实现提案。这应该与规范最终包含的细节程度大致相同:应该能够让独立的程序员根据提案的规范编写互相兼容的实现。
兼容性 :是否会有后续版本的I2P与不遵循提案的版本兼容?如果兼容,如何实现兼容性?一般来说,我们尽量不丢弃兼容性;自2008年3月以来,我们还没有进行过“旗日”更改,我们也不想再进行一次。
实现 :如果提案在I2P的当前架构中难以实现,文档可以包含一些关于如何实现它的讨论。实际补丁应该放在公共monotone分支上,或上传到Trac。
性能和可扩展性注意事项 :如果功能会影响性能(在RAM、CPU、带宽方面)或可扩展性,应该有一些分析来确定这种影响的重要性,以便我们可以避免真正昂贵的性能回归,并避免浪费时间在微不足道的收益上。
参考 :如果提案引用外部文档,这些文档应该被列出。
提案状态
开放 :正在讨论的提案。
接受 :提案已完成,我们打算实现它。在此之后,应该避免对提案进行实质性更改,并将其视为流程在某个地方失败的迹象。
完成 :提案已被接受并实现。在此之后,提案不应该被更改。
关闭 :提案已被接受、实现并合并到主规范文档中。在此之后,提案不应该被更改。
拒绝 :我们不会按照此处描述的功能来实现它,尽管我们可能会实现其他版本。请参阅文档中的评论以获取详细信息。在此之后,提案不应该被更改;要提出其他版本的想法,请编写一个新提案。
草稿 :这还不是一个完整的提案;缺少明确的部分。请不要添加任何新的具有此状态的提案;相反,将它们放在“ideas”子目录中。
需要修订 :提案的想法很好,但提案本身存在严重问题,阻止它被接受。请参阅文档中的评论以获取详细信息。
死亡 :提案已经有一段时间没有被触碰了,它看起来像没有人会很快完成它。如果有人重新提出它,可以使其再次成为“开放”状态。
需要研究 :在清楚提案是否是一个好主意之前,需要解决一些研究问题。
元 :这不是一个提案,而是一个关于提案的文档。
保留 :此提案不是我们目前计划实现的东西,但我们可能会在某一天重新提出它,如果我们决定做类似的事情。
信息 :此提案是正在做的事情的最后一个词。如果没有人将其复制并粘贴到新的子系统的新规范中,它不会变成规范。
编辑器根据粗略的共识和自己的判断来维护提案的正确状态。
提案编号
000-099之间的编号保留用于特殊和元提案。100及以上用于实际提案。编号不会被回收。