GEP-1
摘要:什么是 GEP?
GEP 代表 Groovy 增强提案。GEP 是一份文档,为 Groovy 开发团队和用户社区提供关于 Groovy、语言、API、集成或基础设施的新功能、增强或更改的信息。无论何时添加或更改是重要的,并且需要详细讨论其理由、设计或对项目的影响,都应考虑编写 GEP。
GEP 的概念从 Python 的 PEP (Python 增强提案) 中获得灵感。
理由:为什么需要 GEP?
对于非平凡、复杂或战略性的功能,邮件列表上的讨论很难领导和跟踪,而且通常不能帮助达成共识。编写一份适当的文档来解释所述功能的设计和影响,可以让想法的发起者和整个社区都有机会提供有趣且有用的反馈,并有助于更好地理解该提案的理由、设计决策和影响。
GEP 包含什么?
GEP
-
由 "负责人" 领导,负责人负责提案的编写和进度
-
分配一个唯一的 "编号"
-
有一个 "标题" 简洁地描述其意图
-
有一个 "类型"
-
有一个 "状态" 提供有关其进度的信息
-
有一个 "版本" 号指示其当前修订版
-
提供 "最后修改" 日期
-
提供 "创建" 日期
-
包含一个 "摘要" 解释 GEP 的意图
-
提供此增强的 "理由"
GEP 的类型可以是以下几种
- 信息
-
如果 GEP 提供有关 Groovy 相关主题的一些信息或指导(此 GEP 属于此类型,以及所有现有 GEP 的列表)
- 功能
-
如果 GEP 关于在 Groovy 中实现新功能、增强或更改
- 流程
-
如果 GEP 描述与 Groovy 项目相关的流程(例如:Groovy 发布流程、如何注册新提交者等)
如果 GEP 是一个功能型 GEP,它还应
-
为其集成定义一个 "目标" Groovy 版本
-
提供一个 "参考实现",该实现由单元测试适当覆盖并加注释(根据需要使用 Groovydoc/JavaDoc/asciidoc),以便 Groovy 社区可以尝试增强功能并提供有用的反馈
-
详细说明对 Groovy 的 "影响",特别是在向后兼容性方面或对其他项目的影响方面
GEP 的 "状态" 可以是
- 草稿
-
当 GEP 目前正在编写中,正在讨论中,但尚未达到准备好在 Groovy 中包含的状态
- 已接受
-
当草稿 GEP 处于不需要任何额外修改的状态,准备集成到 Groovy 中,并且已按照通常的 Apache 原则被开发团队接受时
- 已拒绝
-
当达成共识或开发团队决定认为不应将该提案集成到 Groovy 中时
- 最终
-
当 GEP 已集成到 Groovy 的发布版本中,并且已在 Groovy wiki 中得到适当的记录时
除了所有这些元数据,根据需要,GEP 还应
-
提供指向现有邮件列表讨论的指针(通过 Nabble、Markmail 或 Ponymail)
-
列出与该功能相关的现有论文或文档,这些论文或文档提供了更多材料来理解概念或实现困难
-
提供示例,显示如何使用该功能以及解决方案的 Groovy 风格程度如何
通用工作流程
Groovy 增强提案的通用工作流程如下
GEP 的起源通常来自 Groovy 邮件列表上关于新功能或更改的讨论,当 Groovy Despot 和开发团队认为需要适当记录和阐述这个新想法时,以便进一步讨论和分析。一般来说,简单的错误修复和次要增强不需要完整的 GEP。GEP 仅在 Groovy PMC 同意的情况下启动。
Groovy PMC 会分配一个唯一的编号,并为该 GEP 创建一个有意义的 "标题"。如果适用,将提出一个建议的目标 Groovy 版本,用于包含该 GEP。该努力的负责人(通常是 GEP 的发起者或其主要开发人员)负责创建 GEP、编写详细文档提出此增强,并最终为目标 Groovy 版本提供分支(或 PR 或补丁)作为参考实现。一旦开发团队和 "负责人" 对 GEP 的状态感到满意,就应决定是否将 GEP 集成到 Groovy 中,并为该任务创建一个 JIRA 问题。根据 Apache 指南,Groovy PMC 对是否接受 GEP 作为最终状态 GEP 有最终决定权。
一旦在适当的 Groovy 存储库中添加了适当的文档,并且参考实现已达到成熟度,并提供了一个涵盖该功能的良好测试套件,GEP 在 Groovy 中的集成即为最终状态。如果 GEP 未能满足 GEP 流程的所有要求,则可以拒绝或推迟 GEP。
参考文献
JIRA 问题
GROOVY-1709: GEP: Groovy 增强提案
更新历史
- 1.0 (2009-03-26)
-
从 Codehaus wiki 中提取的版本
- 2.0 (2018-10-11)
-
更新以反映加入 Apache 后的更改