版本格式:主版本号.次版本号.修订号
,版本号递增规则如下:
主版本号.次版本号.修订号
”的后面,作为延伸。在软件管理的领域里存在着被称作“依赖地狱”的死亡之谷,系统规模越大,加入的包越多,你就越有可能在未来的某一天发现自己已深陷绝望之中。
在依赖高的系统中发布新版本包可能很快会成为噩梦。如果依赖关系过高,可能面临版本控制被锁死的风险(必须对每一个依赖包改版才能完成某次升级)。而如果依赖关系过于松散,又将无法避免版本的混乱(假设兼容于未来的多个版本已超出了合理数量)。当你项目的进展因为版本依赖被锁死或版本混乱变得不够简便和可靠,就意味着你正处于依赖地狱之中。
作为这个问题的解决方案之一,我提议用一组简单的规则及条件来约束版本号的配置和增长。这些规则是根据(但不局限于)已经被各种封闭、开放源码软件所广泛使用的惯例所设计。为了让这套理论运作,你必须先有定义好的公共 API。这可能包括文档或代码的强制要求。无论如何,这套 API 的清楚明了是十分重要的。一旦你定义了公共 API,你就可以透过修改相应的版本号来向大家说明你的修改。考虑使用这样的版本号格式:X.Y.Z
(主版本号.次版本号.修订号
)修复问题但不影响 API 时,递增修订号;API 保持向下兼容的新增及修改时,递增次版本号;进行不向下兼容的修改时,递增主版本号。
我称这套系统为“语义化的版本控制”,在这套约定下,版本号及其更新方式包含了相邻版本间的底层代码和修改内容的信息。
SemVer
)以下关键词 MUST
、MUST NOT
、REQUIRED
、SHALL
、SHALL NOT
、SHOULD
、SHOULD NOT
、 RECOMMENDED
、MAY
、OPTIONAL
依照 [RFC 2119](https://www.rfc-editor.org/info/rfc2119)
的叙述解读。
X.Y.Z
的格式,其中 X
、Y
和 Z
为非负的整数,且禁止(MUST NOT)在数字前方补零。X
是主版本号、Y
是次版本号、而 Z
为修订号。每个元素必须(MUST)以数值来递增。例如:1.9.1
-> 1.10.0
-> 1.11.0
。0.y.z
)的软件处于开发初始阶段,一切都可能随时被改变。这样的公共 API 不应该被视为稳定版。1.0.0
的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。Z
(x.y.Z | x > 0
)必须(MUST)在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。Y
(x.Y.z | x > 0
)必须(MUST)在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须(MUST)递增。也可以(MAY)在内部程序有大量新功能或改进被加入时递增,其中可以(MAY)包括修订级别的改变。每当次版本号递增时,修订号必须(MUST)归零。X
(X.y.z | X > 0
)必须(MUST)在有任何不兼容的修改被加入公共 API 时递增。其中可以(MAY)包括次版本号及修订级别的改变。每当主版本号递增时,次版本号和修订号必须(MUST)归零。ASCII
字母数字和连接号 [0-9A-Za-z-]
组成,且禁止(MUST NOT)留白。数字型的标识符禁止(MUST NOT)在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例:1.0.0-alpha
、1.0.0-alpha.1
、1.0.0-0.3.7
、1.0.0-x.7.z.92
。ASCII
字母数字和连接号 [0-9A-Za-z-]
组成,且禁止(MUST NOT)留白。当判断版本的优先层级时,版本编译信息可(SHOULD)被忽略。因此当两个版本只有在版本编译信息有差别时,属于相同的优先层级。范例:1.0.0-alpha+001
、1.0.0+20130313144700
、1.0.0-beta+exp.sha.5114f85
。主版本号
、次版本号
、修订号
及先行版本号
后进行比较(版本编译信息不在这份比较的列表中)。主版本号
、次版本号
及修订号
以数值比较。例如:1.0.0
< 2.0.0
< 2.1.0
< 2.1.1
。主版本号
、次版本号
及修订号
都相同时,改以优先层级比较低的先行版本号决定。例如:1.0.0-alpha
< 1.0.0
。主版本号
、次版本号
及修订号
的两个先行版本号,其优先层级必须(MUST)透过由左到右的每个被句点分隔的标识符来比较,直到找到一个差异值后决定:
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
。<valid semver> ::= <version core> | <version core> "-" <pre-release> | <version core> "+" <build> | <version core> "-" <pre-release> "+" <build> <version core> ::= <major> "." <minor> "." <patch> <major> ::= <numeric identifier> <minor> ::= <numeric identifier> <patch> ::= <numeric identifier> <pre-release> ::= <dot-separated pre-release identifiers> <dot-separated pre-release identifiers> ::= <pre-release identifier> | <pre-release identifier> "." <dot-separated pre-release identifiers> <build> ::= <dot-separated build identifiers> <dot-separated build identifiers> ::= <build identifier> | <build identifier> "." <dot-separated build identifiers> <pre-release identifier> ::= <alphanumeric identifier> | <numeric identifier> <build identifier> ::= <alphanumeric identifier> | <digits> <alphanumeric identifier> ::= <non-digit> | <non-digit> <identifier characters> | <identifier characters> <non-digit> | <identifier characters> <non-digit> <identifier characters> <numeric identifier> ::= "0" | <positive digit> | <positive digit> <digits> <identifier characters> ::= <identifier character> | <identifier character> <identifier characters> <identifier character> ::= <digit> | <non-digit> <non-digit> ::= <letter> | "-" <digits> ::= <digit> | <digit> <digits> <digit> ::= "0" | <positive digit> <positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" <letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
这并不是一个新的或者革命性的想法。实际上,你可能已经在做一些近似的事情了。问题在于只是“近似”还不够。如果没有某个正式的规范可循,版本号对于依赖的管理并无实质意义。将上述的想法命名并给予清楚的定义,让你对软件使用者传达意向变得容易。一旦这些意向变得清楚,弹性(但又不会太弹性)的依赖规范就能达成。
举个简单的例子就可以展示语义化的版本控制如何让依赖地狱成为过去。假设有个名为“救火车”的函数库,它需要另一个名为“梯子”并已经有使用语义化版本控制的包。当救火车创建时,梯子的版本号为 3.1.0
。因为救火车使用了一些版本 3.1.0
所新增的功能,你可以放心地指定依赖于梯子的版本号大于等于 3.1.0
但小于 4.0.0
。这样,当梯子版本 3.1.1
和 3.2.0
发布时,你可以将直接它们纳入你的包管理系统,因为它们能与原有依赖的软件兼容。
作为一位负责任的开发者,你理当确保每次包升级的运作与版本号的表述一致。现实世界是复杂的,我们除了提高警觉外能做的不多。你所能做的就是让语义化的版本控制为你提供一个健全的方式来发行以及升级包,而无需推出新的依赖包,节省你的时间及烦恼。
如果你对此认同,希望立即开始使用语义化版本控制,你只需声明你的函数库正在使用它并遵循这些规则就可以了。请在你的 README
文件中保留此页链接,让别人也知道这些规则并从中受益。
最简单的做法是以 0.1.0
作为你的初始化开发版本,并在后续的每次发行时递增次版本号。
当你的软件被用于正式环境,它应该已经达到了 1.0.0
版。如果你已经有个稳定的 API 被使用者依赖,也会是 1.0.0
版。如果你很担心向下兼容的问题,也应该算是 1.0.0
版了。
主版本号为零的时候就是为了做快速开发。如果你每天都在改变 API,那么你应该仍在主版本号为零的阶段(0.y.z
),或是正在下个主版本的独立开发分支中。
这是开发的责任感和前瞻性的问题。不兼容的改变不应该轻易被加入到有许多依赖代码的软件中。升级所付出的代价可能是巨大的。要递增主版本号来发行不兼容的改版,意味着你必须为这些改变所带来的影响深思熟虑,并且评估所涉及的成本及效益比。
为供他人使用的软件编写适当的文档,是你作为一名专业开发者应尽的职责。保持项目高效的一个非常重要的部分是掌控软件的复杂度,如果没有人知道如何使用你的软件或不知道哪些函数的调用是可靠的,要掌控复杂度会是困难的。长远来看,使用语义化版本控制以及对于公共 API 有良好规范的坚持,可以让每个人及每件事都运行顺畅。
一旦发现自己破坏了语义化版本控制的规范,就要修正这个问题,并发行一个新的次版本号来更正这个问题并且恢复向下兼容。即使是这种情况,也不能去修改已发行的版本。可以的话,将有问题的版本号记录到文档中,告诉使用者问题所在,让他们能够意识到这是有问题的版本。
由于没有影响到公共 API,这可以被认定是兼容的。若某个软件和你的包有共同依赖,则它会有自己的依赖规范,作者也会告知可能的冲突。要判断改版是属于修订等级或是次版等级,是依据你更新的依赖关系是为了修复问题或是加入新功能。对于后者,我经常会预期伴随着更多的代码,这显然会是一个次版本号级别的递增。
自行做最佳的判断。如果你有庞大的使用者群在依照公共 API 的意图而变更行为后会大受影响,那么最好做一次主版本的发布,即使严格来说这个修复仅是修订等级的发布。记住, 语义化的版本控制就是透过版本号的改变来传达意义。若这些改变对你的使用者是重要的,那就透过版本号来向他们说明。
弃用现存的功能是软件开发中的家常便饭,也通常是向前发展所必须的。当你弃用部分公共 API 时,你应该做两件事:
没有,请自行做适当的判断。举例来说,长到 255
个字符的版本已过度夸张。再者,特定的系统对于字符串长度可能会有他们自己的限制。
“v1.2.3
” 并不是一个语义化的版本号。但是,在语义化版本号之前增加前缀 “v” 是用来表示版本号的常用做法。在版本控制系统中,将 “version
” 缩写为 “v
” 是很常见的。比如:git tag v1.2.3 -m "Release version 1.2.3"
中,“v1.2.3
” 表示标签名称,而 “1.2.3
” 是语义化版本号。
有两个推荐的正则表达式。第一个用于支持按组名称提取的语言(PCRE
[Perl 兼容正则表达式,比如 Perl
、PHP
和 R
]、Python
和 Go
)。
参见:https://regex101.com/r/Ly7O1x/3/
^(?P<major>0|[1-9]\d*)\.(?P<minor>0|[1-9]\d*)\.(?P<patch>0|[1-9]\d*)(?:-(?P<prerelease>(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+(?P<buildmetadata>[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
第二个用于支持按编号提取的语言(与第一个对应的提取项按顺序分别为:major
、minor
、patch
、prerelease
、buildmetadata
)。主要包括 ECMA Script(JavaScript)
、PCRE
(Perl
兼容正则表达式,比如 Perl
、PHP
和 R
)、Python
和 Go
。 参见:https://regex101.com/r/vkijKf/1/
^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
语义化版本控制的规范是由 Gravatars
创办者兼 GitHub
共同创办者 Tom Preston-Werner 所建立。
如果您有任何建议,请到 GitHub 上提出您的问题。
本文作者:蒋固金
本文链接:
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!