1.4.2.1. 语义化版本
在治理大规模 Terraform 模块时，版本管理是不可动摇的基础。Terraform 和其他软件代码有个很大的不同点：代码一旦应用，就直接影响云上的真实资源，比如创建、修改、甚至删除基础设施。如果引入破坏性变更，轻则导致服务中断，重则可能直接引发数据丢失。
这就是为什么我们强调语义化版本（Semantic Versioning，简称 SemVer）：它是帮助用户判断“这次更新有没有风险”的重要信号。
版本号的格式长这样：
主版本号.次版本号.修订号
比如：1.4.2、2.0.0、0.9.7。
这三个数字分别意味着：
1.4.2.1.1. 主版本号
当模块发生不兼容的变更时，要升级主版本号。
举个例子：假设你的模块里原本有个叫 enable_monitoring 的输入参数，你决定重命名为 monitoring_enabled。用户如果不修改配置，运行时就会报错。这种改动就属于“破坏性变更”，主版本号必须加 1，比如从 1.x.x 升到 2.0.0。
简单来说：破坏兼容 = 升主版本号。
⚠️ 特别提示：Terraform 模块的破坏性变更不只是“配置不兼容”，它可能导致云资源被销毁重建，甚至触发数据丢失风险！这和普通软件升级的“出 bug”完全不同，必须格外慎重。
1.4.2.1.2. 次版本号
当你在模块中新增了向后兼容的新功能时，升级次版本号。
比如你新增了 tags 参数，允许用户给资源加自定义标签，但老功能都没动。这时候可以从 1.3.2 升到 1.4.0。
简单来说：新增功能但不破坏 = 升次版本号。
1.4.2.1.3. 修订号
只做了小修复或小优化时，升级修订号。
比如修复了 terraform plan 阶段的提示信息拼写错误，或者更新了一下模块的文档。这时可以从 1.4.0 升到 1.4.1。
简单来说：修 bug、小改进 = 升修订号。
1.4.2.1.4. 为什么语义化版本很关键
对我们来说，SemVer 的作用绝不只是“看起来很专业”。它能做到：
- 让用户看一眼就懂：有没有风险，是不是必须花时间检查配置。
- 配合自动化工具：比如 Terraform Registry 会根据 SemVer 判断依赖是否满足条件，CI/CD 也能用它控制升级策略。
- 降低沟通成本：不用每次都和用户解释“这次能不能无痛升级”，版本号自己说话。
1.4.2.1.5. 集中式治理：主版本更新窗口
虽然 SemVer 本身定义很清楚，但 Terraform 模块的特殊性决定了一个大规模治理的新要求：
破坏性变更不能随便发布！
如果你维护的模块是内网小团队在用，主版本随时升级问题不大。但一旦管理的是上百个模块、服务上百个团队甚至外部客户，频繁推送破坏性变更就是灾难——没人有精力天天盯着升级文档。
因此，我们的治理建议是：
✅ 建立全局统一的“主版本更新窗口期”，比如每半年或一年开放一次。
在这个窗口期内：
- 模块维护者可以集中发布主版本升级，打包所有计划内的破坏性变更。
必须提供详细的升级文档，明确指出：
- 具体哪些参数、输出、逻辑有变动；
- 如何修改现有配置适配新版本；
- 可能涉及的云端风险提示（比如哪些资源会被销毁重建）。
甚至要考虑提供一些工具帮助用户进行代码迁移，例如我们后面会介绍的 mapotf。
这相当于“有计划地引入风险”，既能推动模块持续进化，又能保障用户有充分的时间和资源做好准备。
1.4.2.1.6. 实际例子
假设你维护一个叫 terraform-aws-network 的模块：
| 版本号 | 变更内容 |
|---|---|
| 1.2.0 | 新增了 enable_flow_logs 参数，向后兼容 |
| 1.2.1 | 修复了 flow logs 子网命名的拼写错误 |
| 2.0.0（集中窗口期） | 删除了旧的 vpc_cidr_block 参数，改为 vpc_cidr |
这里的 2.0.0 就是利用主版本更新窗口统一发布的，把积累了半年或一年的破坏性改动一次性放出，降低用户的升级负担。
1.4.2.1.7. 小结
一句话总结：语义化版本不是单纯的规范，而是 Terraform 模块治理的生命线。
对于大规模治理：
- 小改动 ➔ 修订号。
- 新增功能 ➔ 次版本号。
- 破坏性改动 ➔ 主版本号 + 集中更新窗口。
提前计划，明确提示，才能建立起用户的信任。