语义化版本控制规范

By Siu 2021/02/22

​ 随着系统规模越大，加入的依赖的包和关联系统越来越多，软件版本的管理就变为非常重要的工作；软件版本的管理问题有可能引发“依赖地狱”，让系统的发布和升级陷入绝望。

​ 本规范引用业内常用的“语义化的版本控制”作为这个问题的解决方案。用一组简单的规则及条件来约束版本号的配置和增长。这些规则是根据已经被各种业内著名软件所广泛使用的惯例所设计。

​ 在这套约定下，版本号及其更新方式包含了相邻版本间的底层代码和修改内容的信息。

1 版本号格式

版本格式 X.Y.Z（又称 Major.Minor.Patch），版本号递增规则如下：

  • 主版本号（X）：当做了不兼容的 API 修改，X 需递增。
  • 次版本号（Y）：当做了向下兼容的功能性新增，Y 需递增。
  • 修订号（Z）：当做了向下兼容的 Bug 修正，Z 需递增。

先行版本号及版本编译元数据可以加到“主版本号.次版本号.修订号”的后面，作为延伸。

例：

  • 2.6.0-rc.1+210205.2
  • 2.6.1+210304.3

2 版本号控制规范

  1. 标准的版本号必须采用 X.Y.Z 的格式，其中 X、Y 和 Z 为非负的整数，且禁止在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号。每个元素必须以数值来递增。例如：1.9.1 -> 1.10.0 -> 1.11.0。
  2. 版本号的软件发行后，禁止改变该版本软件的内容。任何修改都必须以新版本发行。
  3. 主版本号为从1开始（1.y.z）；通常0被用于软件开发初始阶段，这里定义软件开发初始阶段用开发版本号来标识，例如：1.0.0-alpha.1+210205.2
  4. X 和 Y 由产品经理指定。
  5. 修订号 Z（x.y.Z ）必须在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。修订号由项目负责人制定。
  6. 次版本号 Y（x.Y.z ）必须在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须递增。也可以在内部程序有大量新功能或改进被加入时递增，其中可以包括修订级别的改变。每当次版本号递增时，修订号必须归零。
  7. 主版本号 X（X.y.z | X > 0）必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须归零。
  • **补充1：**不兼容修改也不允许下线已发布的API
  • **补充2：**关联系统间的依赖，必须等待被依赖版本发布之后，依赖版本才能发布。

  1. 先行版本号可以被标注在修订号之后，先加上一个连接符-，再加上一连串以句点分隔的标识符来修饰。标识符必须由 ASCII 小写字母、数字和连接符- 组成，且禁止留白。数字型的标识符禁止在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。

  2. 版本编译元数据可以被标注在修订版或先行版本号之后，先加上一个加号+再加上一连串以句点分隔的标识符来修饰。标识符必须由 ASCII 小写字母、数字和分隔符.组成，且禁止留白。当判断版本的优先层级时，版本编译元数据可被忽略。因此当两个版本只有在版本编译元数据有差别时，属于相同的优先层级。范例：1.0.0-rc.1+210205.2、1.0.0-alpha+210205.2、1.0.0+210205.2、1.0.0-beta+210205.2。

    • 补充1：规定编译元数据第一段和第二段限制为：Build Date（编译日期，6位）和 Build ID（编译ID，非负整型数值）；其它元数据信息禁止添加。
    • 补充2：编译元数据必须由编译工具自动生成，一经发布禁止修改。

  3. 版本的优先层级指的是不同版本在排序时如何比较。

    • 判断优先层级时，必须把版本依序拆分为主版本号、次版本号、修订号及先行版本号后进行比较（版本编译元数据不影响排序）。
    • 由左到右依序比较每个标识符，第一个差异值用来决定优先层级：
      • 主版本号、次版本号及修订号以数值比较，例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。
      • 当主版本号、次版本号及修订号都相同时，改以优先层级比较低的先行版本号决定。例如：1.0.0-alpha < 1.0.0。
      • 有相同主版本号、次版本号及修订号的两个先行版本号，其优先层级必须透过由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后决定：只有数字的标识符以数值高低比较，有字母或连接号时则逐字以 ASCII 的排序来比较。数字的标识符比非数字的标识符优先层级低。若开头的标识符都相同时，栏位比较多的先行版本号优先层级比较高。范例：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0。

  4. 相关联前端和后端应用的版本号控制

    • 前端应用、后端应用独立管理版本号。

    • 前端应用、后端应用主版本号、次版本号的迭代控制是统一的。

    • 前后端应用主版本号、次版本号相同时，任意版本必须是兼容的。

      • 例如：demo-sys 2.6.Z 版本与它的前端应用 demo-sys-web 2.6.Z 是兼容的

    • 前端应用对应多个后端应用（后端每个应用又相对独立、代码位于各自的仓库中）：

      • 后端各应用设置一个统一的产品版本号（保存于一个公共仓库）与前端应用版本号对应

      • 各后端应用按上述版本号规范，管理自己的内部版本号和统一的产品版本号

      • 例：

        当前已发布 前端 2.6.0 ；后端统一产品版本号 2.6.0 （内部版本号：后端 A 1.2.0 后端 B 2.3.0）

        • 修订版1（后端 A 兼容性修复bug）：前端 2.6.0 ；后端统一产品版本号 2.6.1 （后端 A 1.2.1 后端 B 2.3.0）
        • 修订版2（后端 B 兼容性修复bug）：前端 2.6.0 ；后端统一产品版本号 2.6.2 （后端 A 1.2.1 后端 B 2.3.1）
        • 修订版3（前端兼容性修复bug）：前端 2.6.1 ；后端统一产品版本号 2.6.2 （后端 A 1.2.1 后端 B 2.3.1）

      • **补充1：**前后端多对多的情况也适用上述规则。

      • **补充2：**规范第6点提到的内部程序有大量新功能或改进被加入时递增次版本号，不需要传递到产品版本的次版本号，而是传递到产品版本号的修订号。

  5. 稳定版本的发布，各版本在试运行 bug 修复完成之后必须及时发布正式版。

    • 补充1：稳定版的版本号即不包含先行版本标识的版本号，意味着这个版本进入稳定阶段。范例：2.6.1+210304.3

参考

Semantic Versioning 2.0.0