Crystal语言项目中的变更日志管理优化方案

变更日志（CHANGELOG）是记录项目版本迭代内容的重要文档，但随着Crystal语言项目的持续发展，其主变更日志文件CHANGELOG.md已经增长到GitHub难以渲染预览的程度（约25kB/每个版本，300行代码/每个版本）。这种情况不仅影响开发者的查阅体验，也暴露出单一文件管理长期变更记录的局限性。

问题分析

当前Crystal项目采用单一变更日志文件的管理方式面临两个核心挑战：

1. 文件体积膨胀：随着每个版本平均增加约25kB内容，文件已超过GitHub的渲染阈值
2. 历史信息冗余：大多数情况下开发者只需要查看最新版本的变更，而历史记录成为"冷数据"

项目此前采用过将1.0之前版本变更移至CHANGELOG.0.md的临时方案，但这只是延缓而非解决问题。

解决方案探讨

技术社区提出了几种有代表性的改进方向：

1. 版本分段管理

• 按主版本分割：类似Node.js的方案，为每个主版本创建独立文件（如CHANGELOG.1.md）
• 按次版本分割：类似Terraform的方案，为每个特性版本维护独立变更日志
• 按年份分割：参考esbuild的做法，以时间维度组织变更记录

2. 架构调整

• 动态变更日志：主分支只保留当前开发版本的变更，历史版本变更归档到release分支
• 文档目录重构：将变更日志文件移至docs目录，建立更清晰的文件结构
• 外部托管：将完整变更日志移至项目网站，仓库内只保留精简版或链接

推荐实施方案

综合技术讨论，最优方案应具备以下特点：

1. 版本化分段：采用按次版本分割的方案，保持与Git分支策略的一致性

   • 主分支CHANGELOG.md仅包含当前开发版本变更
   • 每个release/xx.xx分支维护对应版本的完整变更记录
   • 历史版本变更归档到docs/changelog目录

2. 构建时聚合：通过CI/CD流程自动生成完整变更日志，可发布到项目文档网站

3. 渐进式迁移：

   mv CHANGELOG.md docs/changelog/1.16.md
   touch CHANGELOG.md  # 仅包含新版本变更
   

实施效益

该方案将带来以下改进：

• 提升GitHub等平台的渲染性能
• 优化开发者体验，快速定位所需版本变更
• 保持历史记录的完整性和可追溯性
• 为未来的自动化文档生成奠定基础

对于开源项目而言，良好的变更日志管理不仅是技术决策，更是项目维护文化的体现。Crystal项目通过这次优化，将建立更可持续的文档维护机制。