EEP 1：EEP 的目的和指南 #

什么是 EEP？ #

EEP 代表 Erlang 扩展提案，或 Erlang 增强流程。它是一个借用自 Python 语言的概念，旨在促进社区参与 Erlang 的开发。本文档很大程度上基于 PEP 1。EEP 是一份设计文档，向 Erlang 社区提供信息，或描述 Erlang 或其流程或环境的新功能。EEP 应提供该功能的简明技术规范和功能原理。

我们希望 EEP 成为提出新功能、收集社区对问题的意见以及记录 Erlang 设计决策的主要机制。EEP 作者负责在社区内建立共识并记录不同的意见。

由于 EEP 作为文本文件维护在版本控制的存储库中，因此它们的修订历史是功能提案的历史记录。

EEP 类型 #

EEP 有两种类型

1. 标准跟踪 EEP 描述了 Erlang 的新功能或实现。

2. 流程 EEP 描述了 Erlang 周围的流程，或提出对流程的更改（或事件）。流程 EEP 类似于标准跟踪 EEP，但适用于 Erlang 语言本身之外的领域。它们可能会提出一个实现，但不是 Erlang 的代码库；它们通常需要社区共识；它们不仅仅是建议，用户通常不能自由地忽略它们。示例包括发布计划、程序、指南、决策过程的更改以及 Erlang 开发中使用的工具或环境的更改。

EEP 工作流程 #

EEP 编辑器分配 EEP 编号并更改其状态。请通过打开拉取请求到存储库 https://github.com/erlang/eep 来创建 EEP。

EEP 流程从 Erlang 的新想法开始。强烈建议单个 EEP 包含单个关键提案或新想法。EEP 的重点越突出，它就越容易成功。如果 EEP 提案显得过于分散或过于广泛，EEP 编辑器保留拒绝 EEP 提案的权利。如有疑问，请将您的 EEP 分成几个重点突出的 EEP。

每个 EEP 都必须有一个拥护者——有人使用下面描述的样式和格式编写 EEP，在适当的论坛中引导讨论，并尝试围绕该想法建立社区共识。EEP 拥护者（又名作者）应首先尝试确定该想法是否适合 EEP。建议发布到 ErlangForum。小的增强或补丁通常不需要 EEP，可以通过创建对 https://github.com/erlang/otp 的拉取请求注入到 Erlang 开发工作流程中。

EEP 拥护者编写 EEP 的粗略但充实的草案，并附有拟议的标题。此草案必须按照下面描述的 EEP 样式编写。EEP 拥护者可以暂时为他们的 EEP 分配下一个可用的 EEP 编号，将其标记为标准跟踪或流程，并赋予其“草案”状态。然后，EEP 拥护者将 EEP 发送到 EEP 存储库 (https://github.com/erlang/eep)。EEP 编辑器不会无理拒绝 EEP。拒绝 EEP 状态的原因包括工作重复、技术上不合理、未提供适当的动机或解决向后兼容性，或不符合 Erlang 的理念。

如果 pre-EEP 被拒绝，作者可以选择将 pre-EEP 提交到 ErlangForum 以帮助充实它，从更广泛的社区获得反馈和共识，并改进 EEP 以便重新提交。

然后，EEP 的作者负责将 EEP 发布到社区论坛，并争取社区对其的支持。在必要时进行更新，EEP 作者可以签入新版本。

标准跟踪 EEP 由两部分组成：设计文档和参考实现。除非参考实现将有助于人们研究 EEP，否则 EEP 应在开始参考实现之前进行审查和接受。标准跟踪 EEP 必须包含一个实现——以代码、补丁或指向相同内容的 URL 的形式——才能被视为最终版本。

EEP 作者负责在将 EEP 提交审查之前收集社区对其的反馈。 未在 ErlangForum 上讨论过的 EEP 将不被接受。 但是，应尽可能避免在公共论坛上进行长时间的开放式讨论。 保持讨论效率的策略包括：在 ErlangForum 中创建新主题，让 EEP 作者在早期设计阶段接受私人评论，设置 wiki 页面等。EEP 作者应在此处自行决定。

一旦作者完成 EEP，他们必须通知 EEP 编辑器它已准备好进行审查。 EEP 由来自 Erlang/OTP 和 Erlang 社区的人员组成的委员会进行审查，他们可以接受或拒绝 EEP，或将其发回给作者进行修订。对于预先确定为可接受的 EEP（例如，它是一个明显的胜利，并且/或者它的实现已经签入），Erlang/OTP 团队也可以发起 EEP 审查，首先通知 EEP 作者并给予他们进行修订的机会。

委员会成员是内部 Erlang/OTP 技术委员会加上为特定情况召集的专家。

为了使 EEP 被接受，它必须满足某些最低标准。它必须是对拟议增强的清晰完整的描述。增强必须代表净改进。拟议的实现（如果适用）必须是可靠的，并且不得过度复杂化解释器。最后，拟议的增强必须与 Erlang 的理念兼容才能被接受。

一旦 EEP 被接受，必须完成参考实现。当参考实现完成并被接受后，状态将更改为“最终”。

EEP 也可以被分配状态“已延迟”。当 EEP 没有进展时，EEP 作者或编辑器可以将 EEP 分配给此状态。一旦 EEP 被延迟，EEP 编辑器可以将其重新分配为草案状态。

EEP 也可以是“已拒绝”。也许在一切都说完之后，它并不是一个好主意。记录这一事实仍然很重要。

EEP 也可以被不同的 EEP 取代，从而使原始 EEP 过时。

EEP 工作流程如下

如果某些流程 EEP 永远不会完成，则它们可能还具有“活动”状态。例如，EEP 1（此 EEP）。

一个成功的 EEP 中应该包含什么？ #

每个 EEP 都应具有以下部分

1. 前导码 – RFC 822 样式的标头，包含有关 EEP 的元数据，包括 EEP 编号、简短描述性标题（最多 44 个字符）、名称，以及可选的每位作者的联系信息等。

2. 摘要 – 对要解决的技术问题的简短（约 200 字）描述。

3. 版权/公共领域 – 每个 EEP 必须明确标记为放置在公共领域（请参阅此 EEP 作为示例）或根据开放出版许可证或 知识共享署名 3.0 许可证获得许可。

4. 规范 – 技术规范应描述任何新语言功能的语法和语义。该规范应足够详细，以便允许竞争的、可互操作的实现。

5. 动机 – 动机对于想要更改 Erlang 语言的 EEP 至关重要。它应该清楚地解释为什么现有的语言规范不足以解决 EEP 解决的问题。没有足够动机的 EEP 提交可能会被直接拒绝。

6. 原理 – 原理通过描述驱动设计的因素以及为什么做出特定的设计决策来充实规范。它应该描述考虑过的替代设计和相关工作，例如，该功能在其他语言中是如何支持的。

   原理应提供社区内达成共识的证据，并讨论讨论期间提出的重要异议或疑虑。

7. 向后兼容性 – 所有引入向后不兼容性的 EEP 都必须包含一个部分，描述这些不兼容性及其严重性。EEP 必须解释作者如何提议处理这些不兼容性。没有充分向后兼容性论述的 EEP 提交可能会被直接拒绝。

8. 参考实现 – 参考实现必须在任何 EEP 被赋予“最终”状态之前完成，但不必在 EEP 被接受之前完成。最好先完成规范和原理并就此达成共识，然后再编写代码。

   最终实现必须包括适用于 Erlang 语言参考或标准库参考的测试代码和文档。

EEP 格式和模板 #

EEP 以 UTF-8 编码的文本文件形式用 Markdown 格式编写。 EEP 33 是一个模板，其中包含有关如何编写 EEP 的说明。

在 存储库 中还有一个 Markdown Perl 程序的版本以及一些用于构建EEP 索引的 Perl 脚本。只需在顶层目录中给出命令 ./build.pl 即可。

EEP 标头前导码 #

每个 EEP 都必须以 RFC 822 样式的标头前导码开始，所有标头都缩进四个空格，使其成为 Markdown 代码样式。 标头必须按照以下顺序出现。 标有“*”的标头是可选的，如下所述。 所有其他标头都是必需的

    Author: <list of authors' real names and optionally, email addrs>
    * Discussions-To: <email address>
    Status: <Draft | Active | Accepted | Deferred | Rejected |
             Final | Replaced>
    Type: <Standards Track | Process>
    * Content-Type: <text/plain | text/x-rst>
    * Requires: <eep numbers>
    Created: <date created on, in dd-mmm-yyyy format>
    * Erlang-Version: <version number>
    Post-History: <dates of postings to erlang-questions>
    * Replaces: <eep number, ...>
    * Replaced-By: <eep number, ...>

然后是 Markdown 水平规则、EEP 编号和标题（作为 Markdown 标头 2）以及一个空行，全部都是必需的

****
EEP <eep number>: <eep title>
----

Author 标头列出了 EEP 的所有作者/所有者的姓名，以及可选的电子邮件地址。Author 标头值的格式必须是

Random J. User <[email protected]>

如果包含电子邮件地址，则为，并且仅为

Random J. User

如果未给出地址。

如果有多个作者，则每个作者都应按照 RFC 2822 继续行约定放在单独的行上。请注意，个人电子邮件地址应被模糊处理，以防止垃圾邮件收集器。

Type 标头指定 EEP 的类型：标准跟踪或流程。

Created 标头记录 EEP 被分配编号的日期，而 Post-History 用于记录将 EEP 的新版本发布到 erlang-questions 的日期。两个标头都应采用 dd-mmm-yyyy 格式，例如 14-Aug-2009。

标准跟踪 EEP 必须包含一个 Erlang-Version 头部，指明该特性将或已在哪个 Erlang 版本中发布。
过程 EEP 不需要 Erlang-Version 头部。版本必须与 Erlang/OTP 项目的 git 标签方案格式相同。

EEP 可以包含一个 Requires 头部，指明此 EEP 依赖的 EEP 编号。

EEP 也可以包含一个 Replaced-By 头部，指明某个 EEP 已被后续的 EEP(s) 废弃；其值是取代当前文档的 EEP(s) 的编号。较新的 EEP(s) 必须包含一个 Replaces 头部，其中包含它废弃的 EEP(s) 的编号。

辅助文件 #

EEP 可以包含辅助文件，例如图表。此类文件必须命名为 eep-XXXX-Y.ext，其中“XXXX”是 EEP 编号，“Y”是一个序列号（从 1 开始），“.ext”被实际的文件扩展名替换（例如“.png”）。

报告 EEP 错误或提交 EEP 更新 #

如何报告错误或提交 EEP 更新取决于多个因素，例如 EEP 的成熟度、EEP 作者的偏好以及您的评论性质。对于 EEP 的早期草案阶段，最好将您的评论和更改直接发送给 EEP 作者。对于更成熟或已完成的 EEP，您可能需要向 EEP 存储库提交更正。

当不确定将您的更改发送到何处时，请先与 EEP 作者和/或 EEP 编辑器确认。

EEP 作者可以通过提交更改到他们的拉取请求来更新 EEP。

转移 EEP 所有权 #

有时，有必要将 EEP 的所有权转移给新的负责人。一般来说，我们希望保留原始作者作为被转移 EEP 的共同作者，但这实际上取决于原始作者。转移所有权的一个好理由是原始作者不再有时间或兴趣更新它或跟进 EEP 流程，或者已经从网络上消失（即无法联系或不回复电子邮件）。转移所有权的一个坏理由是因为您不同意 EEP 的方向。我们尝试围绕 EEP 达成共识，但如果不可能，您始终可以提交竞争的 EEP。

如果您有兴趣承担 EEP 的所有权，请发送消息询问是否接管，收件人包括原始作者和 EEP 编辑器。如果原始作者没有及时回复电子邮件，EEP 编辑器将做出单方面决定（这并不意味着此类决定不能被撤销:）。

版权 #

本文档置于公共领域或 CC0-1.0-Universal 许可之下，以较宽松者为准。