安道

博客文章

语义性版本号

版本号对一个程序来说是很重要的,我以前是根据自己对其他程序的观察和自我理解为程序制定版本号的,因为似乎没有这方面的规范可以依据。如果程序只是自己或者小范围内使用这也没有大碍,不过如果你的程序被作为其他程序的依赖库,那么你就要重视这个问题了,含糊不清的版本号可能会给其他程序带来不必要的麻烦。

很巧的是,昨天我发现了“语义性版本号”(Semantic Versioning)这个项目,这个项目旨在为你提供一个参考规范,可以更好的为你的程序制定版本号,而且可以让版本号更具语义性。使用 Jekyll 或者对 Github 有所了解的人对这个项目的发起人可能很熟悉,他就是 Github 的联合创始人之一 Tom Preston-Werner(Gravatar 居然也是他创建的,卖给 WordPress 应该赚了不少钱),所以这个参考规范的可行性还是很高的。

下面是我对“语义性版本号”的 12 条参考规范的简单翻译,以后我的程序会严格按照这些规范来制定版本号。

  1. 使用“语义性版本号”的软件必须声明一个公共 API。这个 API 可以在代码中声明,也可以在文档中详细说明。不论采用哪种方式,都要保证准确性和完整性。

  2. 常规的版本号必须使用 X.Y.Z 的格式,其中 X、Y 和 Z 是非负整数。X 是主版本号,Y 是次版本号,Z 是补丁版本号。每部分必须按照数字顺序递增 1。例如:1.9.0 -> 1.10.0 -> 1.11.0

  3. 在提升主版本号的时候,次版本号和补丁版本号必须归零。在提升次版本号的时候,补丁版本号必须归零。例如:1.1.3 -> 2.0.0 -> 2.2.0

  4. 一旦某个版本的程序已经打包发布,这个版本下的内容就一定不可以改动。如需改动则必须发布新版本。

  5. 主版本号为零(0.y.z)意味着处在初期开发阶段。所有内容随时都可能改变。公共 API 不应该被认为是稳定的。

  6. 版本到达 1.0.0 说明公共 API 已经定义完成。在此之后的版本号提升取决于公共 API 的变化。

  7. 只有在引入了向后兼容的错误修正时才必须提升补丁版本号 Z(x.y.Z,其中 x > 0)。错误修正的定义是:为了修正不正确的表现而对内部代码做出的改动。

  8. 在为公共 API 引入新的或向后兼容的功能时必须提升次版本号 Y(x.Y.z,其中 x > 0)。在弃用任何公共 API 后必须提升次版本号。如果为私有代码引入了大量的新功能或是改进,可以提升次版本号。次版本号的提升可能会包含补丁等级的变化。次版本号提升后,补丁版本号必须归零。

  9. 如果为公共 API 引入了对向后不兼容的改变,必须提升主版本号 X(X.y.z,其中 X > 0)。这可能会包含次版本和补丁等级的变化。主版本号提升后,次版本号和补丁版本号必须归零。

  10. 预览版可以通过在补丁版本号后直接添加一个连字符和点分标识符串进行注明。这个点分标识符串只能包含 ASCII 表中的数字、字母和连字符([0-9A-Za-z-])。预览版版本号是一种常用的形式,但是它比相应的常规版本号优先级要低。例如:1.0.0-alpha,1.0.0-alpha.1,1.0.0-0.3.7,1.0.0-x.7.z.92

  11. 构建版可以通过在补丁版本号后或预览版版本号后直接添加一个加号和点分标识符串进行注明。这个标识符串只能包含 ASCII 表中的数字、字母和连字符([0-9A-Za-z-])。构建版版本号是一种常用的形式,但是它比相应的常规版本号优先级要高。例如:1.0.0+build.1,1.3.7+build.11.e0f985a

  12. 优先级的计算必须先将版本号拆分成主版本号、次版本号、补丁版本号、预览版版本号和构建版版本号,然后按照这个顺序进行比较。主版本号、次版本号和补丁版本号按照数字顺序比较。预览版和构建版的优先级必须将各自的点分标识符串分开后按照以下方法比较:只包含数字的标识符按照数字顺序比较;包含字母或连字符的标识符按照 ASCII 表的顺序比较。数字标识符都比非数字标识符的优先级低。例如:1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0-rc.1+build.1 < 1.0.0 < 1.0.0+0.3.7 < 1.3.7+build < 1.3.7+build.2.b8f12d7 < 1.3.7+build.11.e0f985a