版本号规范

版本号规范

语义化版本 SemVer、标签策略

---

SemVer 规则

版本格式

• Requirement：所有对外发布的软件产物必须遵循 语义化版本 2.0.0，格式为 MAJOR.MINOR.PATCH。

MAJOR.MINOR.PATCH
  │     │     └── PATCH：向后兼容的缺陷修复
  │     └──────── MINOR：向后兼容的新功能
  └────────────── MAJOR：不兼容的破坏性变更

递增规则

版本位	触发条件	示例
MAJOR	存在不兼容的 API 变更 / 破坏性变更	1.2.3 → 2.0.0
MINOR	新增向后兼容的功能	1.2.3 → 1.3.0
PATCH	向后兼容的缺陷修复	1.2.3 → 1.2.4

• Requirement：MAJOR 版本变更必须在 CHANGELOG 与 Release Notes 中明确列出破坏性变更及迁移指南。
• Standard：MINOR 版本发布时，已废弃（deprecated）的 API 不得移除，仅可在 MAJOR 版本中移除。
• Standard：首次正式发布版本为 1.0.0；0.x.x 版本处于快速迭代期，API 可能随时变更。

初始开发阶段（0.x.x）

• Standard：0.1.0 为首个可发布版本。
• Standard：0.x.y 阶段，MINOR 可包含破坏性变更（不强制升 MAJOR），但必须在 Release Notes 中说明。
• Caution：0.0.x 仅用于内部原型，不得对外发布。

---

版本号递增

递增决策流程

1. 本次变更是否包含 不兼容的 API 变更？
   • 是 → MAJOR +1，MINOR 和 PATCH 归零。
2. 本次变更是否包含 新功能（向后兼容）？
   • 是 → MINOR +1，PATCH 归零。
3. 本次变更仅为 缺陷修复？
   • 是 → PATCH +1。

示例

1.2.3  →  修复 bug          →  1.2.4
1.2.3  →  新增功能           →  1.3.0
1.2.3  →  破坏性 API 变更    →  2.0.0
1.2.3  →  重构（无 API 变更） →  1.2.4（若无功能新增）

自动递增

Standard：建议使用 release-please 或 semantic-release 根据 Conventional Commits 自动递增版本号：

Commit 类型	版本递增
feat	MINOR
fix	PATCH
feat! / fix!（带 !）	MAJOR
BREAKING CHANGE footer	MAJOR
chore / docs / style / refactor / test	不发布新版本（默认配置下）

---

标签命名

Git Tag 命名

• Requirement：发布版本必须打 Git Tag，标签格式为 v<MAJOR>.<MINOR>.<PATCH>，前缀 v 必须小写。
• Requirement：标签必须打在对应版本的提交上，且为 附注标签（annotated tag），附带发布信息。

# 正确
git tag -a v1.2.3 -m "Release v1.2.3: add OAuth2 login"
 
# 错误
git tag 1.2.3              # 无前缀 v
git tag V1.2.3             # 大写 V
git tag v1.2.3             # 轻量标签（无 -a）

标签保护

• Requirement：已发布的标签 禁止删除或修改（immutable）。如需修复，发布新版本并打新标签。
• Standard：标签推送需通过 CI 自动完成，禁止手动推送标签到生产仓库。

产物版本号

• Standard：构建产物（Docker 镜像、npm 包、二进制文件）的版本号必须与 Git Tag 一致。
• Standard：Docker 镜像标签需同时打版本号与 latest（仅对稳定版）：

docker build -t myapp:v1.2.3 -t myapp:latest .

• Caution：生产环境禁止使用 latest 标签部署，必须使用明确的版本号。

---

预发布版本

预发布标识

• Standard：预发布版本在 PATCH 后追加连字符与预发布标识，格式为 MAJOR.MINOR.PATCH-<prerelease>。

1.0.0-alpha.1
1.0.0-beta.2
1.0.0-rc.1

预发布阶段标识

标识	含义
alpha	内部测试版，功能不完整，可能有重大缺陷
beta	公开测试版，功能基本完整，可能有未知缺陷
rc	发布候选版（Release Candidate），功能冻结，仅修 bug

• Standard：预发布标识后必须跟递增序号，如 alpha.1、alpha.2。
• Standard：预发布版本排序遵循 SemVer 规则：alpha < beta < rc < 正式版。

1.0.0-alpha.1 < 1.0.0-alpha.2 < 1.0.0-beta.1 < 1.0.0-rc.1 < 1.0.0

预发布标签

• Standard：预发布版本的 Git Tag 格式为 v1.0.0-alpha.1。
• Caution：预发布版本不得打 latest 标签。

---

废弃版本

废弃策略

• Requirement：废弃 API 时，必须：
  1. 在当前 MINOR 版本中标记为 @deprecated，但保留功能。
  2. 在文档中说明替代方案与移除计划（目标 MAJOR 版本）。
  3. 至少保留一个 MAJOR 版本的过渡期。
  4. 在目标 MAJOR 版本中正式移除。

废弃标识示例

Python：

import warnings
 
def old_api():
    warnings.warn(
        "old_api() is deprecated since v1.3.0, use new_api() instead. "
        "Will be removed in v2.0.0.",
        DeprecationWarning,
        stacklevel=2,
    )
    return new_api()

TypeScript：

/**
 * @deprecated Use newApi() instead. Will be removed in v2.0.0.
 */
function oldApi(): void {
  return newApi();
}

版本弃用通告

• Standard：每个版本的 Release Notes 必须包含 “Deprecations” 章节，列出本次新增的废弃项。
• Standard：每个 MAJOR 版本的 Release Notes 必须包含 “Removed” 章节，列出本次移除的废弃项。

示例：废弃生命周期

v1.3.0  标记 oldApi() 为 @deprecated，文档推荐 newApi()
v1.4.0  保留 oldApi()，控制台输出废弃警告
v1.5.0  保留 oldApi()，警告级别提升
v2.0.0  移除 oldApi()，调用将报错

反模式

• ❌ 不告知用户直接移除 API（无废弃过渡期）。
• ❌ 在 PATCH 版本中引入破坏性变更。
• ❌ 预发布版本号不带序号（1.0.0-alpha 应为 1.0.0-alpha.1）。
• ❌ 标签使用大写 V 或省略 v 前缀。
• ❌ 已发布标签被删除或覆盖。
• ❌ 生产环境使用 latest 镜像标签部署。