CTCA CTCA
登录

10.1 版本号规范

规范的版本号体系有助于追踪文档变更历史，并帮助用户快速识别文档的更新范围。

版本号概述

版本号是标识文档或软件特定发布状态的编号。在技术文档领域，推荐采用语义化版本号（Semantic Versioning，简称 SemVer）体系。语义化版本号的核心思想是通过版本号的变化传达变更的性质和影响范围，使文档使用者无需阅读完整的变更日志即可判断更新的重要程度。

语义化版本号由三个数字组成，格式为 MAJOR.MINOR.PATCH：

  • MAJOR（主版本号）：进行了不兼容的重大变更，如文档结构重组、内容大幅调整
  • MINOR（次版本号）：新增了向后兼容的内容，如添加新章节、补充新功能说明
  • PATCH（修订号）：进行了向后兼容的内容修正，如修复错别字、更正技术错误
R-160 推荐

文档版本号应与产品版本号对应

技术文档的版本号应与其所描述的产品版本号保持对应关系。当产品发布新版本时，相关文档也应同步更新版本号。文档封面或页眉应清晰标注文档版本号和对应的产品版本号，避免用户使用过时的文档。

R-161 推荐

使用语义化版本号

技术文档应采用语义化版本号（MAJOR.MINOR.PATCH）体系。主版本号在文档结构发生重大变更时递增，次版本号在新增内容时递增，修订号在修正错误或细微调整时递增。每次递增高位版本号时，低位版本号归零。

语义化版本号示例

# 语义化版本号格式：MAJOR.MINOR.PATCH
# MAJOR — 不兼容的重大变更
# MINOR — 向后兼容的新功能
# PATCH — 向后兼容的问题修复

v1.0.0    # 首次正式发布
v1.1.0    # 新增用户管理功能
v1.1.1    # 修复登录页面显示问题
v2.0.0    # 架构重构，API 不兼容旧版本
预发布版本如何编号？

预发布版本可以在版本号后添加连字符和标识符来表示。常见的预发布标识包括：

  • alpha：内部测试版，如 v2.0.0-alpha.1
  • beta：外部测试版，如 v2.0.0-beta.1
  • rc：发布候选版（Release Candidate），如 v2.0.0-rc.1

预发布标识符后的数字表示该阶段的迭代次数。预发布版本的优先级低于正式版本，即 v2.0.0-alpha.1 < v2.0.0-beta.1 < v2.0.0-rc.1 < v2.0.0。

文档独立于产品发布时如何编号？

当技术文档的更新周期与产品发布周期不一致时，可以采用以下策略：

  • 使用独立的文档版本号，但在文档中明确标注「适用于产品 vX.Y.Z」
  • 文档版本号的主版本号与产品主版本号保持一致，次版本号和修订号独立递增
  • 在文档的版本历史页面中记录每次文档更新对应的产品版本范围
内部草稿如何标记版本？

内部草稿阶段的文档版本标记建议：

  • 使用 v0.x.x 表示初始开发阶段，此阶段的文档可能随时发生重大变更
  • 在文档标题或页眉添加「草稿」「DRAFT」水印
  • 标注草稿日期和作者，如「Draft v0.3.0 - 2026-01-10 - 张三」
  • 内部评审版本可使用后缀标记，如 v0.3.0-review.1 表示第一轮评审版

当文档进入正式发布阶段时，版本号应从 v1.0.0 开始。