GLEP 1：GLEP 目的和指南

鸣谢

GLEP 的概念，事实上，本文的大部分内容，都大量借鉴了 Python 的 [1] PEP [2]，特别是 Barry A. Warsaw、Jeremy Hylton 和 David Goodger 编写的 PEP-0001 [3]。

什么是 GLEP？

GLEP 代表“Gentoo Linux 增强提案”。GLEP 是一种设计文档，用于向 Gentoo Linux 社区提供信息，或描述 Gentoo Linux 的新功能。GLEP 应提供该功能的简洁技术规范和基本原理。

我们希望 GLEP 成为提出 *重要* 新功能、收集社区对某个问题的意见以及记录 Gentoo Linux 设计决策的主要机制。GLEP 作者负责在社区内达成共识并记录不同意见。

由于 GLEP 作为文本文件保存在 VCS 中，因此其修订历史是功能提案的历史记录 [4]。对于较旧的 GLEP，基本存储库可能提供更改的大致历史记录。原始更改仍可在 [5] 中找到（针对 2013 年 6 月之前的更改）和/或 [6] 中找到（针对 2013 年 6 月至 2017 年 9 月的更改）。

GLEP 的种类

GLEP 有两种类型。标准跟踪 GLEP 描述了 Gentoo Linux 的新功能或实现。信息性 GLEP 为 Gentoo Linux 社区提供一般准则或信息，但不提出新功能。信息性 GLEP 不一定代表 Gentoo Linux 社区的共识或建议，因此用户和实施者可以自由忽略信息性 GLEP 或遵循其建议。

GLEP 工作流程

GLEP 编辑分配 GLEP 编号并更改其状态。请将所有与 GLEP 相关的电子邮件发送到 <glep@gentoo.org>。

GLEP 流程始于 Gentoo Linux 的一个新想法。强烈建议单个 GLEP 包含一个关键提案或新想法。GLEP 越专注，就越有可能成功。GLEP 编辑保留拒绝 GLEP 提案的权利，如果这些提案显得过于不专注或过于广泛。如有疑问，请将 GLEP 分成几个重点明确的 GLEP。

每个 GLEP 必须有一位负责人——负责使用下面描述的样式和格式编写 GLEP，在适当的论坛中引导讨论，并尝试围绕该想法建立社区共识的人。GLEP 负责人（也称为作者）应首先尝试确定该想法是否适合 GLEP。小的增强或补丁通常不需要 GLEP，并且可以通过提交给 Gentoo Linux bugzilla 的增强“错误” [7] 注入到 Gentoo Linux 开发工作流程中。

然后，GLEP 负责人会在 Bugzilla 中为 GLEP 产品提交一个错误，位于“文档”产品的“新的 GLEP 提交”组件下，并在 GLEP 存储库的专用分支或该存储库的私有 fork 上准备一个粗略但完整的 GLEP 草稿。此草稿必须按照下面和 GLEP 2 中描述的 GLEP 样式编写。

如果 GLEP 编辑接受 GLEP，他们将为 GLEP 分配一个编号，将其标记为标准跟踪（这里需要一个更好的名称——有建议吗？）或信息性，将其状态设置为“草稿”，并将 GLEP 的初始草稿合并到存储库的主分支。GLEP 编辑不会无理拒绝 GLEP。拒绝 GLEP 状态的原因包括工作重复、技术上不合理、未提供适当的动机或解决向后兼容性问题，或不符合 Gentoo Linux 的理念。

如果预 GLEP 被拒绝，作者可以选择将预 GLEP 发送到 gentoo-dev@lists.gentoo.org 邮件列表（对于技术 GLEP）或 gentoo-project@lists.gentoo.org 邮件列表（对于非技术 GLEP），以帮助完善它，获得来自整个社区的反馈和共识，并改进 GLEP 以重新提交。

然后，GLEP 作者负责将 GLEP 发布到 gentoo-dev 或 gentoo-project 邮件列表（如果他们愿意，还可以发布到 Gentoo Linux 论坛 [8]），并为其争取社区支持。如有必要更新，GLEP 作者应请求 GLEP 编辑将更改合并到主分支。

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

GLEP 作者有责任在提交 GLEP 以供审查之前收集社区对其的反馈。未在邮件列表中讨论的 GLEP 将不会被接受。但是，在任何可能的情况下，都应避免在公开邮件列表上进行长时间的开放式讨论。保持讨论效率的策略包括为主题设置特定的论坛主题、让 GLEP 作者在早期设计阶段接受私人评论等。GLEP 作者应在此处自行判断。

作者完成 GLEP 后，必须通过相应的邮件列表通知 Gentoo 委员会 [9] 它已准备好供审查。然后，在委员会会议上审查 GLEP，在会议上可以批准或直接拒绝 GLEP，或将其退回给作者进行修改。这通常应在实际审查前几周完成，以避免在没有 Gentoo 开发者社区的适当公开审查的情况下“偷偷”提交 GLEP 的现象。任何修订都应添加到 Bugzilla 上的 GLEP 错误中。

要获得批准，GLEP 必须满足某些最低标准。它必须是对拟议增强的清晰完整描述。增强必须代表净改进。拟议的实现（如果适用）必须可靠，并且不得过度复杂化发行版。最后，拟议的增强必须满足 Gentoo Linux 的理念。

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

GLEP 还可以被分配“延迟”状态。当 GLEP 没有取得进展时，GLEP 作者或编辑可以为 GLEP 分配此状态。一旦 GLEP 被延迟，GLEP 编辑可以将其重新分配到草稿状态。

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

“撤回”状态与此类似——这意味着 GLEP 作者已决定 GLEP 实际上是一个坏主意，或者已接受竞争性提案是更好的选择。

GLEP 也可以被另一个 GLEP 替换，从而使原始 GLEP 过时（例如，策略的版本 2 可能替换版本 1）。

如果“最终”GLEP 过时并且不需要明确替换，则可以将其标记为“垂死”。

GLEP 工作流程如下

Draft -> Accepted -> Final -> Replaced
  ^                    |
  +----> Rejected      +----> Moribund
  |
  +----> Withdrawn
  v
Deferred

如果某些信息性 GLEP 从未打算完成，例如 GLEP 1（本 GLEP），则它们也可以具有“活跃”状态。

成功的 GLEP 应该包含哪些内容？

每个 GLEP 应包含以下部分

1. 前言——RFC 2822 样式的标题，包含有关 GLEP 的元数据，包括 GLEP 编号、简短的描述性标题（限制为最多 44 个字符）、每个作者的姓名以及可选的联系信息等。

   在下面进一步描述。

2. 摘要——简要描述（约 200 字）正在解决的技术问题。

3. 动机——对于想要修改 Gentoo Linux 功能的 GLEP，动机至关重要。它应该清楚地解释为什么现有的功能或策略不足以解决 GLEP 解决的问题。没有充分动机的 GLEP 提交可能会被直接拒绝。

4. 规范——技术规范应描述此 GLEP 将影响的 Gentoo Linux 的特定领域。如果引入了新功能，该功能将影响哪些软件包？如果是新策略，谁将受到影响？

5. 基本原理——基本原理通过描述设计动机以及为什么做出特定设计决策来阐述规范。它应该描述已考虑的替代设计和相关工作，例如其他发行版中如何支持该功能。

   基本原理应提供社区内部共识的证据，并讨论在讨论过程中提出的重要异议或疑虑。

6. 向后兼容性——所有 GLEP 必须包含一个部分，描述任何向后兼容性问题及其严重性。GLEP 必须解释作者如何提议处理这些不兼容性。（即使没有，也应包含此部分以明确说明这一事实。）没有充分的向后兼容性论述的 GLEP 提交可能会被直接拒绝。

7. 参考实现——在任何 GLEP 获得“最终”状态之前，必须完成参考实现，但不必在 GLEP 被接受之前完成。最好先完成规范和基本原理，并在编写代码或显着修改 ebuild 之前达成共识。

8. 版权——每个新的 GLEP 必须明确标明已获得知识共享署名-相同方式共享 4.0 国际许可证 (CC-BY-SA-4.0) [10] 的许可。在更新时，应将根据 CC-BY-SA-3.0 发布的旧 GLEP 重新许可为 CC-BY-SA-4.0。

GLEP 格式和模板

GLEP 是使用 ReStructuredText 标记语言 [11] 编写的 UTF-8 编码文本文件，然后使用 Docutils [12] 转换为 HTML。ReStructuredText 允许使用丰富的标记语言，这些标记语言仍然非常易于阅读，但也生成美观且功能强大的 HTML。GLEP 2 包含一个用于 ReStructuredText GLEP 的样板模板 [13]。

为了实现最佳互操作性，使用 ReStructuredText 格式的 GLEP 必须使用.rst

GLEP 标题

每个 GLEP 都与某些属性相关联。当 GLEP 发送到邮件列表以供讨论时，应以 RFC 2822 样式的标题序言开头，标题序言位于两条三条虚线之间。标题必须按以下顺序出现。为了实现互操作性，标题序言也应符合 YAML 标准 [14]。标有“*”的标题是可选的。所有其他标题都是必需的。

  ---
  GLEP: <glep number>
  Title: <glep title>
  Author: <list of authors' real names and optionally, email addrs>
  Type: <Informational | Standards Track>
  Status: <Draft | Active | Accepted | Deferred | Withdrawn | Rejected |
           Final | Replaced | Moribund>
  Version: <major>[.<minor>]
  Created: <date created on>
  Last-Modified: <date of last update>
  Post-History: <dates of postings to mailing lists>
  Content-Type: <text/x-rst>
* Requires: <glep numbers>
* Replaces: <glep numbers>
* Replaced-By: <glep number>
  ---

Author 标题列出了所有 GLEP 作者/所有者的姓名，以及可选的电子邮件地址。任何向 GLEP 提交更改的人员都应添加到此字段中。Author 标题值的格式必须为

Random J. User <address@example.org>

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

Random J. User

如果未提供地址。

如果有多个作者，则每个作者应位于单独的一行上，并遵循 RFC 2822 续行约定。作者列表以逗号分隔，即除最后一行外，所有行都必须以逗号结尾。

Type 标题指定 GLEP 的类型：信息性或标准跟踪。

Version 字段指定 GLEP 的当前版本。版本由主版本组成，后跟可选的次版本（如果非零）。每个 GLEP 从版本 1 开始，随着更改合并到 GLEP 中而依次递增。

每当 GLEP 的含义发生变化时，应递增主版本号（并将次版本号重置为零）。对于不影响基本含义的更改（例如澄清、参考实现更新），应递增次版本号。编辑更改应在不增加版本的情况下合并。

Created 标题记录分配 GLEP 编号的日期，Last-Modified 指定 GLEP 在主分支中上次更新的日期，而 Post-History 用于记录将 GLEP 的新版本发布到相应邮件列表的日期。所有三个标题都应使用 ISO 8601yyyy-mm-dd格式，例如 2001-08-14，日期以 UTC（协调世界时）表示。

GLEP 的格式由 Content-Type 标题指定，对于 ReStructuredText GLEP，该标题必须为“text/x-rst”（请参阅 GLEP 2 [13]）。

GLEP 可以具有 Requires 标题，指示此 GLEP 依赖的 GLEP 编号。

GLEP 还可以具有 Replaces 标题，指示 GLEP 旨在替换一个或多个较旧的 GLEP。一旦此类 GLEP 被接受，应将匹配的 Replaced-By 添加到所有被替换的 GLEP 中，并且其状态应更新为 Replaced。

报告 GLEP 错误或提交 GLEP 更新

如何报告错误或提交 GLEP 更新取决于几个因素，例如 GLEP 的成熟度、GLEP 作者的偏好以及您的评论的性质。对于 GLEP 的早期草稿阶段，最好将您的评论和更改直接发送给 GLEP 作者或评论 GLEP 错误。对于更成熟或已完成的 GLEP，您可能希望将更正提交到 Gentoo Linux bugzilla [7]，“Documentation”产品的“GLEP Changes”组件下，以避免您的更改丢失。请务必在错误中抄送 GLEP 作者。如果您不确定将更改发送到哪里，请先咨询 GLEP 作者和/或 GLEP 编辑。

GLEP 作者必须让 GLEP 编辑将他们的更改合并到主分支中，因为写入权限仅限于 GLEP 编辑，以保护 GLEP 的完整性。

任何对 GLEP 的重大更新（即更改 GLEP 内容而不是仅修复错别字或添加少量说明的更新）都应在合并之前获得 Gentoo 委员会的批准。

转移 GLEP 所有权

有时需要将 GLEP 的所有权转移到新的负责人。通常，我们希望保留原始作者作为已转移 GLEP 的共同作者，但这实际上取决于原始作者。转移所有权的一个好理由是，原始作者不再有时间或兴趣更新它或遵循 GLEP 流程，或者已经消失在网络上（即无法联系或没有回复电子邮件）。转移所有权的一个坏理由是您不同意 GLEP 的方向。我们试图围绕 GLEP 建立共识，但如果不可能，您可以随时提交一个竞争性 GLEP。

如果您有兴趣承担 GLEP 的所有权，请发送一条请求接管的消息，发送给原始作者和 GLEP 编辑 <glep@gentoo.org>，或评论 GLEP 错误。如果原始作者未及时回复电子邮件，GLEP 编辑将做出单方面决定（这并不意味着此类决定无法撤销 :)）。

参考文献和脚注

版权

本作品根据知识共享署名-相同方式共享 4.0 国际许可协议授权。要查看此许可证的副本，请访问 https://creativecommons.org/licenses/by-sa/4.0/。