开源项目中的版本号如何规范？

本文目录导读：

1. 核心规范：语义化版本控制
2. 何时使用语义化版本？
3. 其他常见版本策略
4. 给开源项目维护者的建议

开源项目中的版本号规范,最主流的是语义化版本控制，它被绝大多数现代开源项目（如 npm、GitHub、Linux 内核的变体）所采用。

下面是详细的规范说明,以及一些其他常见但不太主流的版本策略。

核心规范：语义化版本控制

这是最通用、最推荐的规范，其版本号格式为：MAJOR.MINOR.PATCH。

• MAJOR (主版本号)：当你做了不兼容的 API 修改时增加。
  • 含义：新版本无法向后兼容，比如你改了函数名、删除了一个功能、修改了请求参数结构。
  • 用户影响：用户必须修改自己的代码才能升级。
• MINOR (次版本号)：当你做了向下兼容的功能性新增时增加。
  • 含义：添加了新功能，但旧代码依然能正常运行。
  • 用户影响：用户可以放心升级，新功能会自然生效，旧功能不受影响。
• PATCH (修订号)：当你做了向下兼容的问题修正时增加。
  • 含义：修复了 Bug、性能问题，没有添加新功能。
  • 用户影响：用户应该立即升级以获取更稳定更好的体验。

一个简单的记忆原则：

版本号 X.Y.Z，当 API 不兼容时（破坏性变更）升 X（主版本号），加新功能升 Y（次版本号），修 Bug 升 Z（修订号）。

进阶规范（常见于 Release 阶段）

在基础版本号之后,还可以添加预发布版本和构建元数据，格式为：MAJOR.MINOR.PATCH-PRERELEASE+BUILD。

• 预发布版本 (Pre-release)：通过连字符 紧跟版本号后，表示该版本不稳定、不完全，仅供测试。
  • 常见后缀：-alpha（内测）、-beta（公测）、-rc.1（候选发布版）。
  • 示例：0.0-alpha.1，3.0-rc.2。
  • 优先级：预发布版本的优先级低于正式版本。0.0-alpha < 0.0。
• 构建元数据 (Build Metadata)：通过加号 紧跟版本号后，表示构建相关的信息，不参与版本优先级比较。
  • 示例：0.0+build.20240315，4.1+sha.9876abc。
  • 作用：方便追踪构建来源，但当你比较版本大小时，0.0+build123 和 0.0+build456 被认为是同一个版本（即 0.0）。

何时使用语义化版本？

• 有明确 API 的项目：库、框架、SDK 或 CLI 工具，用户需要依赖它、调用它的接口。
• 需要明确依赖管理：如 npm、Maven、pip、Cargo 等包管理器。

其他常见版本策略

并非所有项目都严格使用语义化版本,以下是一些变体：

1. 日期/日历版本：格式如 03.15 或 03。

   • 使用场景：大型复杂项目，功能发布与日历强相关，且不强调“破坏性变更”的明确定义。
   • 例子：Ubuntu (22.04, 24.04)，Ubuntu 版本本身就是日期。Python 的 12.0 中 .12 也隐含了年份。
   • 优缺点：容易知道“新不新”，但难以判断兼容性。

2. 统一版本号 (Unity Versioning)：所有组件共享一个版本号（如 0.0）。

   • 使用场景：一个项目包含多个子模块（前端、后端、数据库迁移脚本），发布时一起打包。
   • 例子：很多内部项目或 Docker 镜像。
   • 注意：这样做会丢失细粒度的兼容性信息。

3. 渐进式增强（如 Linux 内核，但非严格的语义化）：

   • Linux 内核的版本号现在基本接近语义化，但历史上（2.6.x 时代）有不同含义，现代 Linux 内核版本如 8.0，基本遵循 MAJOR.MINOR.PATCH，但 -rc1、-next 等预发布机制非常活跃。

4. 慢速发布：保持 y.z 很长一段时间。

   • 例子：软件尚未成熟，1.0、2.0 等。x 版本不做严格向后兼容承诺。注意：语义化规范中，y.z 不被视为正式发布，可以随时做破坏性变更。

给开源项目维护者的建议

1. 优先选择语义化版本：这是公认的标准，用户理解成本最低，依赖管理工具（如 npm’s 、）也是基于它设计的。
2. 严格区分 MAJOR 和 MINOR：即使是修改一个返回值的类型，如果会导致用户代码报错，也属于破坏性变更，必须升 MAJOR。
3. 预发布版本要小心：-rc.1（Release Candidate）表示功能已冻结，只待修复 Bug；-beta 表示还在加功能或改接口，不要在 -rc 之后突然加个破坏性功能。
4. 考虑使用“版本生命周期”：0.0 (Current)，1.0 (Active)，2.0 (LTS)，0.0 (Next)，但版本号本身仍应严格遵循语义化。
5. 保持一致性：一旦确定版本策略，就在项目的 README、CONTRIBUTING 和 CHANGELOG 中明确说明，并严格执行。

• 最推荐：语义化版本控制 (MAJOR.MINOR.PATCH)，配合 -alpha、-beta、-rc。
• 记住核心：
  • MAJOR：破坏性变更（不兼容）
  • MINOR：功能性新增（向后兼容）
  • PATCH：问题修正（向后兼容）
• 什么时候可以例外：如果你的项目不是 API 库（比如一个图形界面应用、一个文档项目、一个内部工具），可以简化版本策略，但为了社区友好，语义化版本依然是最好的选择。

遵循规范能让你的项目更专业,让用户（以及依赖管理工具）安心地使用和升级。