.. _semantic-versioning: Semantic Versioning (SemVer) ============================================================================== Keywords: SemVer, Semantic, Version, Versioning, Open Source .. contents:: :class: this-will-duplicate-information-and-it-is-still-useful-here :depth: 1 :local: Summary ------------------------------------------------------------------------------ Semantic Versioning = 语义化版本号. 是一种软件版本号的命名规范. 简单来说符合这个规范有助于让用户一眼就能从版本号获得很多有用的信息. 版本号格式是 ``major.minor.patch``. - major: 主版本号, 当你做了不兼容的 API 修改 - minor: 次要版本号, 当你做了向下兼容的功能性更新 - patch: 当你做了向下兼容的问题修正 先行版本号及版本编译信息可以加到 ``major.minor.patch`` 的后面, 作为延伸. Semantic Versioning Specification ------------------------------------------------------------------------------ 1. 使用 SemVer 的软件必须定义公共 API. 这些 API 需要被包含在代码内部, 并且被文档记录下来. 注: 在 Python 的世界里, 你的包里必须要有一个 ``api.py`` 文件, 里面定义所有以非下划线开头的类, 变量, 都被视为公共 API. 而这个 ``api.py`` 最终要被 ``__init__.py`` 所导入. 2. 版本号 ``X.Y.Z`` 必须都是非负整数, 禁止在前面补零. 0 是可以的. 3. 版本一旦被发型, 禁止改变版本的内容. 如果你想改, 请发布新版本. 这个叫做 immutable release. 4. Major 版本号处于 0 的软件处于开发初始阶段, 一切都可能随时被改变. 这样的公共 API 不应该被视为稳定版. 5. 1.0.0 的版本号用于界定公共 API 的形成. 这一版本之后所有的版本号更新都基于公共 API 及其修改内容. 6. 修订号 Z (x.y.Z | x > 0) 必须 (MUST) 在只做了向下兼容的修正时才递增. 这里的修正指的是针对不正确结果而进行的内部修改. 7. 次版本号 Y (x.Y.z | x > 0) 必须 (MUST) 在有向下兼容的新功能出现时递增. 在任何公共 API 的功能被标记为弃用时也必须 (MUST) 递增. 也可以 (MAY) 在内部程序有大量新功能或改进被加入时递增. 其中可以 (MAY) 包括修订级别的改变. 每当次版本号递增时, 修订号必须 (MUST) 归零. 8. 主版本号 X (X.y.z | X > 0) 必须 (MUST) 在有任何不兼容的修改被加入公共 API 时递增. 其中可以 (MAY) 包括次版本号及修订级别的改变. 每当主版本号递增时, 次版本号和修订号必须 (MUST) 归零. 9. 先行版本号可以 (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``. 10. 还有很多不是那么重要的, 请参考原文. FAQ ------------------------------------------------------------------------------ - Q: 在 0.y.z 初始开发阶段, 我该如何进行版本控制? - A: 最简单的做法是以 0.1.0 作为你的初始化开发版本, 并在后续的每次发行时递增次版本号. - Q: 如何判断发布 1.0.0 版本的时机? - A: 当你的软件被用于正式环境, 它应该已经达到了 1.0.0 版. 如果你已经有个稳定的 API 被使用者依赖, 也会是 1.0.0 版. 如果你很担心向下兼容的问题, 也应该算是 1.0.0 版了. Reference ------------------------------------------------------------------------------ - https://semver.org/