语义化版本管理

说明

1. 此处是原文网址链接
2. 本文没有任何商业目的，也禁止任何商业目的的使用，转载，引用等
3. 如有侵权，请联系删除

概要

给出一个的版本号 MAJOR.MINOR.PATCH，出现下面的情况增加与之对应的版本号：

1. 增加 MAJOR 版本，当做出一些非兼容性 API 修改，
2. 增加 MINOR 版本，当以向后兼容的方式添加一些功能性修改，
3. 增加 PATCH 版本，当修复了一些向后兼容的问题。

用于预发布和构建的元数据的附加标签可以作为 MAJOR.MINOR.PATCH 格式的扩展。

介绍

在软件管理的世界里，有一个可怕的地方叫做“依赖地狱”。系统越大，集成到软件中的软件包越多，您就越有可能在某一天发现自己陷入绝望的深渊。

在具有许多依赖项的系统中，发布新的包版本会很快成为一场噩梦。如果依赖规范太紧，你就会面临版本锁定的危险(无法升级软件包如果不发布每个依赖包的新版本)。如果依赖关系的指定过于松散，你将不可避免地受到版本混乱的影响(假设与未来版本的兼容性超过了合理水平)。依赖地狱就是当出现版本锁定和/或版本混乱阻止你轻松安全地将项目向前推进时的情况。

作为这个问题的解决方案，我提出了一组简单的规则和需求，它们规定了版本号是如何分配和增加的。这些规则是建立在封闭软件和开放源代码软件中普遍使用的实践基础上的，但并不一定仅限于此。要使这个规则系统工作，首先需要声明一个公共API。这可以由文档组成，也可以由代码本身强制执行。不管怎样，这个API必须清晰和精确。一旦你确定了你的公共API，你就可以通过特定的版本号增量来表示对其所做的修改。采用 X.Y.Z(Major.Minor.Patch) 的版本格式 。不影响API的Bug修复增加 Patch 版本，向后兼容的 API 添加/更改增加 Minor 版本，向后不兼容的 API 更改增加 Major 版本。

我称这个版本系统为“语义化版本管理”。在这个方案下，版本号及版本变化方式传达了底层代码的含义，以及从一个版本到下一个版本的修改内容。

语义化版本管理规范（SemVer）

本文件中的关键词 “MUST”，“MUST NOT”，“REQUIRED”，“SHALL”，“SHALL NOT”，“SHOULD”，“SHOULD NOT”，“RECOMMENDED”，“MAY”和”OPTIONAL“按RFC 2119中的描述理解。

1. MUST：本词或术语“REQUIRED”或“SHALL”指的是定义是规范的绝对要求。
2. MUST NOT：本短语或“SHALL NOT”短语的意思是定义是绝对禁止的规范。
3. SHOULD：本词或者形容词“RECOMMENDED”表示在特殊情况下可能存在合理有效的理由去忽略特定的项目，但在选择不同的方向前必须理解其全部含义，并仔细权衡。
4. SHOULD NOT：本短语，或者这个短语”NOT RECOMMENDED“ 表示在特殊情况下存在合理有效的理由，表明特定的行为是可接收的或甚至是更有用的，但是在实现这个标签描述的任何行为之前，应该理解其完整的含义并仔细的权衡。
5. MAY：本词，或形容词“OPTIONAL”，表示一个项目是 真正地可选。一个供应商可能会选择包括该项目，因为一个特定的市场需要它，或者因为供应商感觉它增强了产品而另一个供应商可能会忽略相同的项目。不包含某个特定选项的实现必须考虑与另一个包括这个特定选项的实现进行交互操作 ，尽管这可能会减少功能。在同样的脉络里一个包含某个特定选项的实现必须考虑与另一个没有包含某个特定选项的实现进行相互交互（当然，除了特定选项提供的功能）。

1. 使用语义化版本管理的软件必须声明一个公开API。这个API可以在代码中声明，也可以严格存在于文档中。一旦这个API定义完成，它应该是精确和全面的。

2. 正常版本号必须采用X.Y.Z的形式，其中X、Y和Z是非负整数，且不能包含前置零（01/02的0）。X是主版本（Major），Y是次版本（Minor），Z是补丁版本（Patch）。每个元素都必须按数字递增。例如：1.9.0 -> 1.10.0 -> 1.11.0。

3. 一旦发布了版本化的包，就不能修在改该版本的内容。任何修改都必须作为新版本发布。

4. 主（Major）版本0（0.y.z）用于初始开发。任何事情都可能在任何时候发生变化。这个版本的公开API不应该被认为是稳定的。

5. 版本1.0.0定义了公共API。这个版本发布以后，版本号增加的方式取决于此公开API及此API变化的方式。

6. 补丁（Patch）版本Z（x.y.Z | x > 0）必须增加，如果只引入向后兼容的错误修复。错误修复定义是修复不正确行为的内部更改。

7. 次（Minor）版本Y (x.Y.z | x > 0）必须增加，如果向公共API引入了向后兼容的新功能。

   • 如果任何公开API功能被标记为deprecated，此版本必须增加。
   • 如果在私有代码中引入了实质性的新功能或改进，此版本号可能会增加。
   • 次版本增加时可能包括补丁级别的更改。当次版本增加时，补丁版本必须重置为0。

8. 主（Major）版本X（X.y.z | X > 0）必须增加，如果向公开API引入任何向后不兼容的更改。

   • 它也可能包括此版本和补丁版本级别的修改。
   • 当主版本增加时，补丁版本和次版本必须重置为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.92，1.0.0-x-y-z.–。

10. 构建的元数据可以通过在补丁或预发布版本之后立即附加一个加号和以一系列点分隔的标识符来表示。

    • 标识符只能由ASCII字母数字和连字符组成 [0-9A-Za-z-]。
    • 标识符不能为空。

    在确定版本优先级时，构建的元数据必须被忽略。因此，仅在构建的元数据方面不同的两个版本具有相同的优先级。例如：1.0.0-alpha+001，1.0.0+20130313144700，1.0.0-beta+exp.sha.5114f85，1.0.0+21AF26D3—-117B344092BD。

11. 优先级指的是排序时版本之间的比较方式。

    1. 优先级必须将版本划分为主、次、补丁和预发布标识符，按照顺序分别比较（构建的元数据不能表明优先级）。

    2. 优先级由下面所列的从左到右进行比较每个标识符时的第一个差异决定：主要、次要和补丁版本总是在数字上进行比较。例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。

    3. 当主版本、次版本和补丁版本相同时，预发布版本的优先级低于正常版本，例如：1.0.0-alpha < 1.0.0。

    4. 具有相同主、次和补丁版本的两个预发布版本的优先级必须将每个以点分隔的标识符从左到右进行比较，直到发现差异时根据下面的规则决定：

       1. 仅由数字组成的标识符按数字进行比较。
       2. 带有字母或连字符的标识符按ASCII排序顺序进行词法比较。
       3. 数字标识符的优先级总是低于非数字标识符。
       4. 如果前面的标识符都相等，那么更大的预发布字段集的优先级要高于更小的预发布字段集。

    示例：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。