)
概要版本号格式主版本号.次版本号.修订号MAJOR.MINOR.PATCH按以下规则递增MAJOR主版本号做了不兼容的API变更时递增MINOR次版本号以向后兼容的方式新增功能时递增PATCH修订号做向后兼容的Bug修复时递增还可以在MAJOR.MINOR.PATCH基础上增加预发布版本标签与构建元数据作为扩展。引言软件依赖管理领域存在一个令人头疼的问题叫做依赖地狱。系统越大集成的软件包越多你就越有可能某天陷入这个困境。在依赖繁多的系统中新版本发布很快就会变成噩梦如果依赖版本约束过严会出现版本锁升级一个包就要同步升级所有依赖它的包。如果依赖版本约束过松就会出现版本泛滥错误地假设可以兼容未来大量更高版本。版本锁、版本泛滥导致项目无法简单、安全地迭代这就是依赖地狱。为此我们提出一套简单的规则与约定用来定义版本号如何分配、如何递增。这套规则参考业界已有的开源/闭源软件实践但不完全照搬。使用这套机制首先你需要定义公开API可以写在文档里也可以由代码本身强制约束。API必须清晰明确。定义好公开API之后就通过版本号的变化来表达API的改动。版本格式记为X.Y.Z主版本.次版本.修订号不改动API仅修复Bug → 修订号1向后兼容新增API功能 → 次版本号1API发生不兼容变更 → 主版本号1我们称之为语义化版本Semantic Versioning。版本号的变化直接传递底层代码的改动信息。语义化版本规范(SemVer)本文中MUST必须、MUST NOT严禁、REQUIRED要求、SHALL应当、SHALL NOT不应、SHOULD建议、SHOULD NOT不建议、RECOMMENDED推荐、MAY可以、OPTIONAL可选按照 RFC 2119 释义。使用语义化版本的软件必须(MUST)声明公开API。API可以写在代码内也可以仅存在于文档建议(SHOULD)做到精确完整。正式版本格式**必须(MUST)**为X.Y.ZX/Y/Z为非负整数禁止(MUST NOT)前导零。X主版本号Y次版本号Z修订号每段数字必须按数值递增。例1.9.0 → 1.10.0 → 1.11.0版本包一旦发布该版本内容绝不允许(MUST NOT)修改修改必须(MUST)发布为新版本。0.y.z主版本为0用于开发初期一切都可能随时改动公开API不保证(SHOULD NOT)稳定。1.0.0代表公开API正式定型。1.0.0之后版本号的变更完全由公开API的改动决定。修订号 Zx.y.Zx0必须(MUST)做向后兼容的Bug修复时递增。Bug修复指修复错误行为的内部改动。次版本号 Yx.Y.zx0新增向后兼容的公开API功能必须(MUST)递增公开API标记废弃必须(MUST)递增私有代码新增大量功能/优化可以(MAY)递增可以(MAY)包含修订级别的修复次版本号增加时修订号必须(MUST)重置为0。主版本号 XX.y.zX0公开API引入不兼容变更必须(MUST)递增可以(MAY)同时包含次版本、修订级别的改动主版本号增加时次版本、修订号必须(MUST)全部重置为0。9.预发布版本在版本核心后面加连字符-后跟若干点分隔的标识符代表预发布版本。标识符只能使用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.9210.构建元数据在版本/预发布版本后加加号()后跟点分隔标识符代表构建元数据。标识符字符约束同上不能为空。版本优先级比较时忽略构建元数据仅构建元数据不同的两个版本优先级相等。示例1.0.0-alpha001、1.0.020130313144700、1.0.0-betaexp.sha.5114f8511.版本优先级版本排序规则优先级用于版本之间大小比较(1) 拆分出主版本、次版本、修订号、预发布标识符构建元数据不参与优先级计算。(2) 从左到右依次对比找到第一个不同项决定大小。主、次、修订号按数值比较。示例1.0.0 2.0.0 2.1.0 2.1.1(3) 主、次、修订号完全相同时预发布版本 正式版本。示例1.0.0‑alpha 1.0.0(4) 同主/次/修订号的两个预发布版本按点分割标识符逐项对比纯数字标识符按数值比较含字母/横杠按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.0BNF语法语义化版本文法validsemver::versioncore|versioncore-pre-release|versioncorebuild|versioncore-pre-releasebuildversioncore::major.minor.patchmajor::numericidentifierminor::numericidentifierpatch::numericidentifierpre-release::dot-separatedpre-releaseidentifiersdot-separatedpre-releaseidentifiers::pre-releaseidentifier|pre-releaseidentifier.dot-separatedpre-releaseidentifiersbuild::dot-separatedbuildidentifiersdot-separatedbuildidentifiers::buildidentifier|buildidentifier.dot-separatedbuildidentifierspre-releaseidentifier::alphanumericidentifier|numericidentifierbuildidentifier::alphanumericidentifier|digitsalphanumericidentifier::non-digit|non-digitidentifiercharacters|identifiercharactersnon-digit|identifiercharactersnon-digitidentifiercharactersnumericidentifier:: 0 |positivedigit|positivedigitdigitsidentifiercharacters::identifiercharacter|identifiercharacteridentifiercharactersidentifiercharacter::digit|non-digitnon-digit::letter| -digits::digit|digitdigitsdigit:: 0 |positivedigitpositivedigit:: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9letter:: 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为什么要用语义化版本这并不是什么全新的理念很多人已经在做类似的事。但“差不多”是不够的。没有正式规范约束版本号对依赖管理几乎没有意义。明确定义语义化版本之后你可以向使用者清晰传递版本意图从而写出松紧适度的依赖约束。举个例子假设有库Firetruck依赖包Ladder。开发Firetruck时Ladder版本为3.1.0用到了3.1.0新增的API。那依赖就可以声明为3.1.0 4.0.0。后续Ladder发布3.1.1、3.2.0都可以安全升级不会破坏上层库。当然现实世界复杂你依然需要做验证。但语义化版本提供一套合理的发布、升级逻辑避免大量依赖包被迫跟着改版本节省大量时间。想要使用语义化版本只需要声明遵循该规范并且照规则执行。可以在README中附上官网链接方便其他人了解。FAQ–常见问题0.y.z开发阶段版本怎么处理最简单初始版本0.1.0每次发布递增次版本号。什么时候发布1.0.0软件已经投入生产环境使用用户已经依赖这套稳定API你开始大量关心向后兼容性。满足以上任意情况就应该升级到1.0.0。会不会阻碍快速迭代0.y.z版本就是用来快速迭代的。如果API天天改动就保持0.y.z或者开分支开发下个大版本。微小的不兼容改动也要升主版本号版本号会不会飙升到42.0.0这考验开发者的设计与预判。对大量使用者的包不兼容变更不能随意做。主版本号强制提升会迫使你评估变更的代价与收益。完整记录公开API文档工作量太大作为面向外部使用者的软件开发者写好文档是你的责任。管理复杂度是项目高效运转的关键如果没人知道哪些接口可以安全调用项目很难维护。长期来看语义化版本 清晰API文档让所有人都更省心。不小心在次版本发布里引入不兼容变更怎么办意识到问题后立刻修复、发布新次版本恢复兼容性。绝对不能修改已经发布的旧版本。视情况记录问题版本告知使用者。只更新内部依赖公开API没变版本怎么变公开API没改动属于兼容变更。要看更新依赖是为了修复Bug还是引入新能力修复Bug走修订号引入新代码/新能力走次版本号。上层项目自己处理依赖冲突。补丁版本错误地引入破坏性API变更怎么办自行权衡。如果受影响用户极多回滚行为冲击很大哪怕严格来说属于Bug修复也直接发布主版本。语义化版本核心是向用户传递变更的意义。如何处理API废弃更新文档告知用户在次版本发布中标记废弃至少保留一个带废弃标记的次版本再在大版本中彻底删除接口给用户充足迁移时间。版本字符串长度有限制吗规范本身没有限制但要合理。例如255字符就过长部分系统会自带限制。v1.2.3是语义化版本吗不是。v只是版本标记前缀。例如git标签v1.2.3标签名带v真正的语义化版本是1.2.3。校验SemVer的正则表达式支持命名分组PCRE、Python、Go等^(?Pmajor0|[1-9]\d*)\.(?Pminor0|[1-9]\d*)\.(?Ppatch0|[1-9]\d*)(?:-(?Pprerelease(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\(?Pbuildmetadata[0-9a-zA-Z-](?:\.[0-9a-zA-Z-])*))?$数字捕获分组兼容JS等ECMAScript环境^(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-])*))?$关于语义化版本规范原始作者Tom Preston‑WernerGravatar发明者、GitHub联合创始人。如果你需要我可以帮你整理一份可直接复制的SemVer速查表方便开发查阅。参考https://semver.org/spec/v2.0.0.html 语义化版本规范https://www.doubao.com 豆包AI翻译
)
