3. 版本管理概念：语义化版本控制（SemVer）、版本号规范、版本分支策略

在工程分析数据平台的主数据模型迁移过程中，版本管理是确保模型可追溯、可回滚、可协作的核心机制。没有规范的版本管理，多团队并行开发将导致模型冲突、依赖混乱，甚至生产事故。本节围绕语义化版本控制（SemVer）、版本号规范与版本分支策略三个维度展开，为后续的迁移脚本编写与测试验证奠定基础。

3.1 语义化版本控制（SemVer）

语义化版本控制（Semantic Versioning，简称 SemVer）是一种广泛采用的版本号格式规范，其核心思想是通过版本号的变化传递代码变更的兼容性信息。对于主数据模型而言，SemVer 能够清晰表达模型结构的破坏性变更、新增字段或属性、以及内部修复或优化。

SemVer 的版本号格式为：MAJOR.MINOR.PATCH，每个部分的递增规则如下：

除了核心三位版本号，SemVer 还支持预发布版本号（Pre-release）和构建元数据（Build Metadata），格式为 MAJOR.MINOR.PATCH-PRE.RELEASE+BUILD。例如：2.1.0-alpha.1+20250315。预发布版本用于内部测试或灰度验证，构建元数据通常记录 CI/CD 构建编号或时间戳。

3.2 版本号规范

为了在团队协作和自动化工具中统一识别版本，需要制定明确的版本号规范。以下是在主数据模型迁移中推荐的版本号规范细则：

• 初始版本：模型首个稳定版本从 1.0.0 开始，而非 0.1.0。这表示模型已具备生产可用性。
• 预发布标签：使用 alpha、beta、rc（Release Candidate）作为预发布标识，按成熟度排序。例如：1.2.0-alpha.1 → 1.2.0-beta.1 → 1.2.0-rc.1 → 1.2.0。
• 版本号不可重复：一旦发布，版本号即被锁定，不可修改或覆盖。任何变更都必须生成新的版本号。
• 版本号与标签对齐：在 Git 仓库中，每个发布的版本必须对应一个 Git Tag，Tag 名称与版本号完全一致，例如 v2.1.0。
• 依赖声明：当主数据模型被其他模块依赖时，使用 ^（兼容次版本）或 ~（兼容修订号）来声明依赖范围，避免自动引入不兼容的主版本变更。

{
  "modelName": "engineering_asset",
  "version": "2.1.0",
  "dependencies": {
    "core_entity": "^1.0.0",
    "measurement_unit": "~0.5.0"
  },
  "preRelease": null,
  "buildMetadata": "20250315.1"
}

3.3 版本分支策略

版本分支策略定义了在版本控制系统中如何管理不同阶段的代码和模型定义。合理的分支策略能够支持并行开发、紧急修复和长期维护。针对主数据模型迁移，推荐采用 Git Flow 与 Trunk-Based Development 的混合策略，兼顾严谨性与敏捷性。

以下是与主数据模型版本管理强相关的核心分支及其职责：

分支策略与版本号的对应关系如下：

• 当 feature 分支合并到 develop 后，次版本号递增（MINOR +1），修订号归零。
• 当 release 分支合并到 main 后，主版本号或次版本号锁定，并打上正式版本 Tag。
• 当 hotfix 分支合并到 main 后，修订号递增（PATCH +1），并打上补丁版本 Tag。

3.4 版本分支策略与主数据模型迁移的协同

在主数据模型迁移场景中，版本分支策略需要与模型定义文件（如 JSON Schema、Avro Schema、Protobuf 定义）的存储位置和变更流程紧密结合。以下是推荐的协同实践：

• 模型定义与代码同源：将主数据模型的 Schema 文件与数据管道代码存放在同一仓库中，确保模型版本与代码版本一一对应。
• 模型变更必须经过分支：禁止直接在 main 或 develop 分支上修改模型定义。所有模型变更必须通过 feature 分支发起，并经过代码审查（Code Review）。
• 迁移脚本与模型版本绑定：每个模型版本对应的向上迁移（Up Migration）和向下回滚（Down Migration）脚本，必须与该版本的 Tag 一起归档。例如，v1.1.0 对应的迁移脚本存放在 migrations/v1.1.0/ 目录下。
• 预发布分支的集成测试：在 release 分支上，必须运行完整的模型兼容性测试套件，包括向前兼容和向后兼容测试，确保模型变更不会破坏已有数据管道。

3.5 版本管理最佳实践清单

为了确保版本管理在主数据模型迁移中落地有效，以下是一份可操作的最佳实践清单：

1. 版本号自动化：在 CI/CD 流水线中集成版本号自动递增工具（如 semver CLI 或 GitVersion），避免人工修改版本号导致的错误。
2. 版本变更日志：维护 CHANGELOG.md 文件，记录每个版本的变更内容、作者、日期和关联的 Issue/PR 编号。格式遵循 Keep a Changelog 规范。
3. 模型兼容性检查：在 CI 中集成 Schema 兼容性检查工具（如 Avro Compatibility Checker 或 Protobuf Breaking Change Detector），自动检测 MAJOR、MINOR、PATCH 级别的变更。
4. 分支保护规则：在 Git 仓库中设置分支保护规则，禁止直接推送到 main 和 develop 分支，要求所有合并必须通过 Pull Request 和至少一名 Reviewer 的批准。
5. 版本 Tag 签名：对发布的版本 Tag 进行 GPG 签名，确保版本号的真实性和不可篡改性。
6. 废弃版本策略：定义模型版本的废弃（Deprecation）策略，明确废弃版本的支持期限和迁移路径，避免长期维护过多历史版本。