Flower 改善文档#

目录#

总结#

改善 Flower 功能是一个标准化的开发流程，目的是

  • 为提出更大规模的改动提供一个共同的结构

  • 确保改动的动机明确

  • 将项目信息保存在版本控制系统中

  • 记录面向用户的具有影响力的改动的动机

  • 保留 GitHub 问题，用于跟踪进行中的工作

  • 确保社区参与者能够成功推动改动，完成一个或多个版本，同时利益相关者在整个过程中得到充分展现

因此，"增强文件"将以下方面结合起来

  • 一个功能和效力跟踪文档

  • 一个产品需要文档

  • 一个设计文档

该文件是与社区合作逐步创建的。

动机#

对于向 Flower 提出的远期变更或功能，需要一个超越单个 GitHub 问题或拉取请求（pull request）的抽象概念，以了解和沟通项目即将发生的变更。

这一流程的目的是减少我们社区中 "部落知识 "的数量。通过将决策从 Slack 线程、视频通话和走廊对话转移到一个跟踪良好的工作环境中，该流程旨在加强沟通和可发现性。

目标#

任何较大的、面向用户的增强都应遵循增强流程。如果要以书面或口头形式向作者或开发人员以外的任何人描述增强功能，则应考虑创建改善文档。

同样，任何会对开发社区的大部分人产生影响的技术工作（重构、重大架构变更）也应广泛传播。即使对典型用户或操作员的影响为零，改进流程也适用于这种情况。

非目标#

对于小的改动和添加，通过 "改善"程序既耗时又没有必要。例如，这包括添加新的联邦学习算法，因为这只会增加功能，而不会改变 "Flower "的工作或使用方式。

增强功能与功能请求不同，因为它们已经提供了实施路径，并得到了社区成员的支持。

提案#

增强功能被记录在一个 Markdown 文件中，该文件遵循已定义的模板和工作流程，用于审查和存储增强功能文档（即增强功能文档）以供参考。

增强文档模板#

每个增强文档都以 Markdown 文件的形式提供，其结构如下

  • 描述数据（如下所述 以 YAML 前言的形式出现）

  • 标题（与描述数据中的标题相同）

  • 目录（如有需要）

  • 总结

  • 动机

    • 目标

    • 非目标

  • 提案

    • 注意事项/限制/警告（可选）

  • 设计细节（可选）

    • 毕业标准

    • 升级/降级策略（如适用）

  • 缺点

  • 备选方案

作为参考，本文件采用上述结构。

描述数据#

  • fed-number（必填）上一个Flower增强文件的 "fed-number "+1。有了这个编号，就很容易参考其他提案。

  • 标题 （必填）用简明语言写出提案的标题。

  • status （必填）提案的当前状态。有关可能的状态，请参阅 工作流程。

  • 作者（必填） 提案的作者列表。这只是 GitHub ID。

  • 创建日期（必填） 建议书在 PR 中首次提交的日期。

  • 最后更新 （可选）提案最后一次重大修改的日期。

  • 另见 （可选）与本提案相关的其他提案清单。

  • 取代（可选） 这份提案所取代的提案列表。

  • 被取代者 （可选） 此提案取代的提案列表。

工作流程#

形成增强功能的想法应该已经在社区中讨论过或提出过。因此，它需要一个支持者（通常是作者）来引导增强。这个人还必须找到愿意审核提案的提交者。

新的增强功能以 NNNN-YYYYMMDD-enhancement-title.md 的文件名签入，其中 NNNN 是花朵增强文档的编号，并将其转入 enhancements。作为拉取请求（pull request）的一部分，所有增强功能都从 provisional 状态开始。讨论是作为拉取请求审查的一部分进行的。

一旦增强功能通过审核和批准，其状态就会变为 可实施。实际的实施工作将在单独的拉取请求中完成。这些拉取请求应在其描述中提及相应的增强功能。实施完成后，提案状态将更改为 已实施。

在某些条件下，还可能出现其他状态。增强提案具有以下状态：

  • 暂定： 已提出改进建议并正在积极定义。这是在提案得到充实、积极定义和讨论时的起始状态。

  • 可实施： 增强功能已审核通过。

  • 已实施： 增强功能已实施，不再主动更改。

  • 推迟： 已提出改进建议，但尚未积极开展工作。

  • 拒绝： 作者和审稿人已决定不再推进该增强功能。

  • 撤回： 作者已撤回增强功能。

  • 已替换： 增强功能已被新的增强功能取代。

缺点#

在 GitHub 已提供的流程（问题和拉取请求）之外再增加一个流程，会增加复杂性，并可能成为潜在首次贡献者的障碍。

对于英语非母语者来说，将提案模板扩展到目前要求的单句描述之外可能是一个沉重的负担。

备选方案#

GitHub 问题#

使用 GitHub Issues 进行此类改进是可行的。例如，我们可以使用标签来区分和过滤这些问题。主要的问题在于讨论和审查增强功能： GitHub 问题只有一个评论线程。而增强功能通常会同时有多个讨论线程，针对文档的不同部分。在使用 GitHub 问题时，管理这些多重讨论会很混乱。

谷歌文档#

谷歌文档允许多线程讨论。但是，由于谷歌文档是在项目之外托管的，因此需要注意它们是否能被社区发现。我们必须管理所有提案的链接列表，并提供给社区使用。与作为 Flower 资源库一部分的提案相比，丢失链接的可能性要大得多。