语义化版本发布规范 - 量潮科技工作教程

这篇文章是干什么的¶

这是一份我们团队自己的语义化版本发布规范。它告诉你版本号怎么定、什么情况发什么版本、从开发到发布整个流程怎么走。

不是翻译语义化版本规范，是我们自己怎么用的文档。读完你会知道下次发版时，该打什么标签、怎么写 changelog、怎么发 release。

版本号长这样：主版本号.次版本号.补丁版本号

每个位置有明确的含义：

看起来简单，但 0.x 阶段和 1.0 之后规则不一样。下面分开讲。

1.0 是对外正式上线的版本。一旦发了 1.0，后面的每一次版本变更都要严格遵守语义化版本的规则。

1.0 是对外的承诺，版本号就是承诺的内容。用户看版本号就知道这次升级要不要改自己的代码。

0.1 是内部正式上线的版本。意味着这个东西内部已经在用了，但还没有对外承诺稳定性。

这个区间的默认假设是：每个次版本号变更都可能有 break change。也就是说，从 0.1 升到 0.2，API 可能不兼容。这是有意为之——内部迭代阶段需要快速调整，API 该改就改，用版本号把变化标清楚就行。

依赖设置的时候，如果限制范围写成 >=0.3, <0.4，就是告诉包管理器：0.3.x 的补丁升级我可以接受，但 0.4 别给我自动升，因为它可能有 break change。DOTA、NPM、Python 的包管理都支持这种语法。

0.1 之前的版本，比如 0.0.1、0.0.2，每个补丁版本都默认假设有 break change。

标准语义化规范是从 0.1 开始的。但社区里大量项目在用 0.0.x，所以我们也跟着这个实践走。这个阶段通常是项目还没上线、正在快速搭骨架的时候。每个版本都在剧烈变动，用补丁号往前滚，不纠结语义，快速迭代，直到觉得稳定了再发 0.1。

实战经验是：这个阶段一次性写好几个版本的规划，边跑边调，等骨架稳定了再正式切到 0.1。

日常发版按这个表判断就够了：

情况	1.0 之后	0.1~1.0	0.1 之前
不兼容的 API 变更	升主版本号	升次版本号	升补丁版本号
向下兼容的新功能	升次版本号	升次版本号	升补丁版本号
向下兼容的修复	升补丁版本号	升补丁版本号	升补丁版本号

如果你改动的东西有明显变化，哪怕只是一个细节修正但对外行为有感知，发一个补丁版本标注出来。有变化就有记录，这是最基本的。

发一个新版本，走三步：

1. 更新 CHANGELOG

把这次改了什么写进 CHANGELOG。格式不用复杂，但要把三类变化说清楚：加了什么、改了什么、修了什么。每个条目一句话，让人一眼扫过去就知道这个版本值不值得升。

2. 打 Git tag

在代码仓库里给发布的那次提交打上版本标签。标签名就用版本号，比如 v0.3.1。附上简短说明，可以是一句话概括这次发布的核心变化。

3. 发 GitHub Release

在 GitHub 上基于刚才打的标签创建 Release。标题用版本号，内容可以直接引用 CHANGELOG 里对应的部分，或者写一段更自然的发布说明。这一步做完，版本发布就完成了——别人能在 Release 页面看到所有历史版本和每个版本的改动。

我们团队有 devops-release 这个 Skill 可以用，在 quanttide-tech 那边。

刚才那次改动就是走了一遍完整流程。直接在 GitHub 上改的，没大修，只是把细节扣了一下。但因为有明显变化，所以发了一个补丁版本标注。改完刷新页面已经能看到了。

这就是补丁版本该干的事：改动不大，但有变化，就标出来。不因为小就不写 changelog，不因为小就不打 tag。每一步都留痕，是给自己留的，也是给以后接手的人留的。