语义化版本惯例
转自 Semantic Versioning 2.0.0,有删改。
一般来说,版本格式最主要的部分是 “主版本号.次版本号.修订号”,递增规则如下:
- 主版本号(
X
):不兼容的 API 修改; - 次版本号(
Y
):向下兼容的功能性新增; - 修订号(
Z
):向下兼容的问题修正。
特别地,当主版本号为 0 时,上述规则没有那么严格,因为前者意味着项目处于快速开发时期。
先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面,作为延伸。
具体地:
- 使用语义化版本控制系统地项目必须定义公共 API。
- 标注地版本号必须为
X.Y.Z
的格式,其中X
、Y
和Z
是非负整数,且禁止在数字前补零。X
是主版本号,Y
是次版本号,Z
为修订号。每个元素必须以数值递增。 - 标记版本号的软件发行后,禁止改变该版本软件的内容。任何修改必须以新版本发行。
- 主版本号为零(
0.y.z
)的软件处于开发初始阶段,一切可能随时被改变。 1.0.0
的版本号用于界定公共 API 的形成。这一版本之后的版本号更新都基于公共 API 及其修改内容。- 修订号
Z
(x.y.Z
|x > 0
)必须在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果进行的内部修改。 - 次版本号
Y
(x.Y.z
|x > 0
)必须在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须递增。也可以在内部程序有大量新功能或改进被加入时递增,其中可以包括修订级别的改变。每当次版本号递增时,修订号必须归零。 - 主版本号
X
(X.y.z
|X > 0
)必须(MUST)在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时,次版本号和修订号必须归零。 - 先行版本号可以被标注在修订版之后,先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须由 ASCII 字母数字和连接号
[0-9A-Za-z-]
组成,且禁止留白。数字型的标识符禁止在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。 - 版本编译信息可以被标注在修订版或先行版本号之后,先加上一个加号再加上一连串以句点分隔的标识符来修饰。标识符必须由 ASCII 字母数字和连接号
[0-9A-Za-z-]
组成,且禁止留白。当判断版本的优先层级时,版本编译信息可被忽略。