Yazi项目版本管理策略探讨：从语义化版本到日历版本

引言

在软件开发领域，版本管理策略的选择直接影响着项目的维护效率和用户体验。Yazi作为一个快速发展的终端文件管理器项目，近期社区就版本管理方案进行了深入讨论，探讨是否应该从传统的语义化版本(SemVer)转向日历版本(CalVer)。

版本管理方案对比

语义化版本(SemVer)采用MAJOR.MINOR.PATCH的格式，其中：

• MAJOR版本号表示不兼容的API修改
• MINOR版本号表示向下兼容的功能新增
• PATCH版本号表示向下兼容的问题修正

而日历版本(CalVer)则基于发布日期，常见格式包括：

• YYYY.MM.DD（完整日期）
• YY.MM（年月）
• YY.MM.X（年月加序列号）

Yazi项目的特殊需求

Yazi作为一个由多个功能子模块组成的复杂系统，包括插件系统、CLI工具和主题风格等。在实践中发现，任何子模块的破坏性变更都会被视为整个项目的破坏性变更，这使得传统的语义化版本难以准确描述项目状态。

日历版本的优势

1. 更直观的时间关联：用户可以直接从版本号判断发布时间
2. 更适合快速迭代项目：Yazi经常会有破坏性变更，日历版本避免了频繁的MAJOR版本号变更
3. 更好的插件兼容性管理：插件可以指定最低支持的Yazi版本

技术实现挑战

在实际实施过程中，团队发现Rust的Cargo工具对日历版本的支持存在限制：

• Cargo不允许版本号中出现前导零
• 这导致在Cargo.toml中必须使用"25.1.1"格式，而发布版本则希望显示为"25.01.1"

插件系统的版本兼容性

采用日历版本后，插件可以通过元数据指定最低支持的Yazi版本：

--- @minVersion 25.01.27
return {
  entry = function() end
}

这种方式确保了插件能够在兼容的环境中运行，当用户尝试在不支持的版本上运行插件时，系统会给出友好的提示。

向后兼容性考量

讨论中也提出了关于向后兼容性的重要问题：

• 如何确保旧插件在新版本中仍能正常工作
• 是否需要维护废弃API的存根实现
• 如何处理长期未维护的插件

决策与实施

经过充分讨论后，Yazi项目决定采用日历版本管理策略，并已在代码库中实现了相关功能。这一变更将带来以下改进：

• 更清晰的版本发布节奏
• 更直观的版本号表示
• 更好的插件生态系统管理

结论

版本管理策略的选择应当基于项目特性和发展需求。对于Yazi这样快速迭代、包含多个子系统的项目，日历版本提供了比传统语义化版本更合适的解决方案。这一变更将有助于项目的长期健康发展，同时为用户和插件开发者提供更好的体验。