Altair项目发布说明管理优化方案探讨

在开源可视化库Altair的维护过程中，开发团队发现当前存在发布说明(release notes)双重维护的问题。目前发布说明同时存在于项目文档和GitHub Releases两个地方，这种重复维护不仅增加了工作量，还导致了内容不一致和质量差异的问题。

现状分析

当前Altair的发布说明维护存在以下特点：

1. 双重维护：发布说明同时在项目文档(使用reStructuredText格式)和GitHub Releases(使用Markdown格式)中维护
2. 内容差异：由于格式限制，GitHub Releases中的发布说明通常包含更丰富的内容，包括图片和更好的格式
3. 维护成本：每次发布都需要在两个地方更新内容，且需要重新格式化

解决方案讨论

开发团队经过深入讨论，提出了几种可能的解决方案：

方案一：统一使用GitHub Releases

优势：

• Markdown格式更易于编写和格式化
• 可以方便地插入图片和代码示例
• 能够直接链接到PR和贡献者
• 降低维护成本，只需维护一个版本

改进措施：

• 在项目文档中保留发布说明入口，但改为链接到GitHub Releases
• 在RELEASING.md文件中临时记录各PR的变更，作为发布时的素材

方案二：统一使用项目文档

优势：

• 所有发布说明集中在一个页面，便于搜索和浏览
• 文档界面更加美观统一
• 用户更习惯查看项目文档

挑战：

• reStructuredText格式限制较多
• 难以实现与GitHub生态的深度集成

技术实现建议

团队还讨论了如何优化发布说明的生成流程：

1. 采用约定式提交(Conventional Commits)：在PR标题中使用前缀如feat、fix、docs等，便于自动分类
2. 自动化生成初稿：利用GitHub的自动生成发布说明功能创建初稿
3. 人工补充完善：在初稿基础上添加详细说明、图片和代码示例

结论

综合各方意见，Altair团队倾向于采用统一使用GitHub Releases的方案，并配合约定式提交和自动化工具来简化发布说明的生成过程。这种方案能够在保证发布说明质量的同时，显著降低维护成本，使团队能够将更多精力投入到功能开发和问题修复中。

这一改进不仅有利于维护团队，也将最终为用户带来更清晰、更详细的版本变更信息，帮助用户更好地了解每个版本的新特性和改进。