软件项目版本号规范

版本格式 X.Y.Z

软件版本号采用 X.Y.Z 的格式。

• X Major(主版本号)：当你做了不兼容的 API 修改
• Y Minor(次版本号)：当你做了向下兼容的功能性新增
• Z Revision(修订号)：当你做了向下兼容的问题修正
• Build 编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。当判断版本的优先层级时，版本编译信息可被忽略

控制规范

1. X、Y 和 Z 为非负的整数，且禁止在数字前方补零
2. 每个元素必须以数值来递增（如：1.9.1 -> 1.10.0 -> 1.11.0）。
3. 标记版本号的软件发行后，禁止改变该版本软件的内容。任何修改都必须以新版本发行。
4. 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变（通常以 0.1.0 作为你的初始化开发版本）。这样的公共 API 不应该被视为稳定版。 1.0.0 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。
5. 修订号 Z（x.y.Z | x > 0）必须在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。
6. 次版本号 Y（x.Y.z | x > 0）必须在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须递增。也可以在内部程序有大量新功能或改进被加入时递增，其中可以包括修订级别的改变。每当次版本号递增时，修订号必须归零。
7. 主版本号 X（X.y.z | X > 0）必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须归零。
8. 版本的优先层级指的是不同版本在排序时如何比较。判断优先层级时，必须把版本依序拆分为主版本号、次版本号、修订号后进行比较（版本编译信息不进行比较）。由左到右依序比较每个标识符号，第一个差异值用来决定优先层级：主版本号、次版本号及修订号以数值比较，例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。

为供他人使用的软件编写适当的文件，是你作为一名专业开发者应尽的职责。

FAQ

1. 万一不小心把一个不兼容的改版当成了次版本号发行了该怎么办？

一旦发现自己破坏了语义化版本控制的规范，就要修正这个问题，并发行一个新的次版本号来更正这个问题并且恢复向下兼容。即使是这种情况，也不能去修改已发行的版本。可以的话，将有问题的版本号记录到文件中，告诉使用者问题所在，让他们能够意识到这是有问题的版本。

2. 我该如何处理即将弃用的功能？

弃用现存的功能是软件开发中的家常便饭，也通常是向前发展所必须的。当你弃用部份公共 API 时，你应该做两件事：（1）更新你的文件让使用者知道这个改变，（2）在适当的时机将弃用的功能透过新的次版本号发布。在新的主版本完全移除弃用功能前，至少要有一个次版本包含这个弃用信息，这样使用者才能平顺地转移到新版 API。

参考资料

• 《Semantic Versioning(语义化版本表示)》