软件版本控制指南生成器

版本控制概述

• 本文档面向 Lumen 日历协作App，适配客户端（iOS/Android/Web）、后端服务与内部共享组件的统一版本管理。
• 采用日历化版本控制（CalVer），以计划性列车发布模型（Release Train）为核心，确保跨团队对齐发布节奏、降低版本歧义、提升可追溯性。
• 版本兼容与风险边界：
  • 同一年度（YYYY）内保障对外接口与数据格式的向后兼容；若必须破坏兼容，需提前两轮月度版本完成弃用公告与灰度路径。
  • 破坏性变更仅允许在年度切换（YYYY 变化）时进入主线，且需提供迁移指引与回滚策略。
• 统一规范与术语：
  • 版本标签采用前缀“v”，如：v2025.06、v2025.06.P1、v2025.06-rc.1。
  • 统一使用UTC为版本纪元（避免时区歧义）；对外沟通可加注本地时区时间。
• 面向角色的产出物：
  • 开发团队：变更清单、接口变更说明、依赖锁定清单。
  • 测试团队：RC 验收清单、回归范围、缺陷基线。
  • 产品团队：范围冻结单、发布说明、已知问题与风险提示。
  • 客户代表：对外发布公告、升级须知、影响评估与回滚预案摘要。

版本号命名规范

• 版本格式（严格定义）：
  • 正式版：vYYYY.MM
  • 紧急修订：vYYYY.MM.Px（x 为从 1 起的递增整数）
  • 预发布：vYYYY.MM-rc.n、vYYYY.MM-beta.n（n 为从 1 起的递增整数）
  • 构建元信息（可选）：+build.<时间戳或摘要>（不影响排序与升级判断）
• 字段语义：
  • YYYY（年）：生命周期锚点。年度切换允许纳入可能的破坏性变更（需严格治理与迁移指引）。
  • MM（月）：计划发布批次。新增功能、性能优化、非破坏性接口扩展在该层级交付。
  • Px（修订）：紧急修复与安全补丁，仅允许包含非功能性变更与缺陷修复，禁止引入功能与数据模型变更。
• 命名规则与校验：
  • 年与月均为零填充（如 2025.06），确保排序一致性。
  • 同一版本号在仓库中唯一且不可重用；已发布标签禁止重写或删除。
  • 预发布标识仅用于验收，不得直接推广至生产；GA 时必须去除预发布后缀。
• 兼容与弃用策略：
  • 同年内对外 API 采用非破坏性演进（新增字段为可选、保留旧字段至少两个月度版本）。
  • 弃用计划需包含：弃用公告（D-2 版本）、可观测警示（服务端日志/告警）、替代方案与迁移文档。
• 示例：
  • 月度正式版：v2025.06
  • 第一次紧急修订：v2025.06.P1
  • 第二个候选版本：v2025.06-rc.2
  • 带构建元信息：v2025.06.P1+build.20250618T1030Z.a1b2c3

分支管理策略

• 基础模型：主干开发（Trunk-Based）+ 短分支 + 发布分支 + 热修分支
• 分支类型与用途：
  • main（受保护）：始终保持可发布状态；仅允许通过受保护合并进入。
  • feature/<简要描述>：短生命周期功能分支；完成后通过评审合并回 main。
  • release/YYYY.MM：在进入发布周期时从 main 切出，承载稳定化、回归修复与文档完善；不接受新功能。
  • hotfix/YYYY.MM.Px：从对应 GA 标签（vYYYY.MM）切出，仅用于紧急修复；合并回 main 与对应 release 分支。
  • 可选maint/YYYY：年度维护分支（若需要年度级 LTS），用于汇聚该年度仍受支持的修订。
• 合并与评审门禁：
  • feature -> main：必须通过代码评审、静态检查、单元与集成测试；禁止直接推送。
  • main -> release：通过「切版」操作一次性分流；切版后仅允许修复类提交。
  • hotfix -> main/release：采用「最小差异」策略；严格要求回归测试与风险评审。
• 提交与标签规范：
  • 建议采用结构化提交信息（如 feat/fix/perf/refactor/docs/test），便于自动生成变更日志与影响面分析。
  • 仅在通过验收门禁后创建 GA 标签（vYYYY.MM 或 vYYYY.MM.Px）；RC 使用预发布标签（-rc.n）。
• 历史与安全：
  • 受保护分支上禁止强制推送、禁止历史重写。
  • 所有合并提交需保留审阅记录与身份验证日志，便于审计。

版本发布流程

1. 版本计划与范围冻结
   • 明确本次 vYYYY.MM 的范围、风险与成功指标（性能、稳定性、兼容性）。
   • 建立需求清单与变更禁止清单（冻结后仅接受阻断级缺陷修复）。
   • 预分配版本号并创建分支：release/YYYY.MM。
2. 稳定化与依赖冻结
   • 在 release 分支上执行依赖冻结（生成/更新锁定文件），禁止引入新依赖或大版本升级。
   • 解决依赖冲突：优先使用兼容范围内的次版本升级或回退；必要时采用受控覆盖（override），并记录复现与验证脚本。
3. 自动化校验（CI 门禁）
   • 编译构建、单元测试、集成测试、端到端关键路径用例。
   • 安全基线：静态扫描、依赖漏洞扫描、秘钥泄露检测、许可证合规。
   • 质量阈值：代码覆盖率、变更热区风险评分、二进制可复现度检查。
4. 预发布与验证
   • 打 RC 标签：vYYYY.MM-rc.1（必要时递增）。
   • 部署至预生产/验收环境，执行回归、性能、兼容、可用性测试；验证数据迁移的扩展-迁移-收缩三步法。
5. 发布评审与签署
   • 由开发、测试、产品、客户代表进行评审；审阅风险、阻断缺陷、回滚预案与对外说明。
   • 满足放行条件后，批准 GA。
6. 正式发布（GA）
   • 创建 GA 标签：vYYYY.MM（不可变）。
   • 渐进式发布：灰度/分批/蓝绿之一，设定可回滚检查点与观察窗口（如 2 小时/24 小时双窗口）。
   • 监控指标：错误率、崩溃率、延迟、关键业务转化、告警阈值与自动回退触发条件。
7. 发布说明与通知
   • 生成结构化发布说明：新增、修复、性能、弃用/破坏性变更、已知问题、升级指导。
   • 通知渠道：内部通告、客户代表对外公告、API 消费方变更提示。
8. 版本收尾与后续
   • 关闭 release 分支或保留以便后续修复（最多一周期）。
   • 将必要修复从 release 回灌 main；更新路线图与弃用时间线。

紧急修复流程

1. 触发条件与分级
   • 影响面达到：严重安全问题、生产阻断、数据不一致或核心功能不可用。
   • 由应急负责人判定是否启动紧急修复（P 修订）。
2. 建立修复分支与范围控制
   • 从 GA 标签 vYYYY.MM 切出：hotfix/YYYY.MM.Px。
   • 原则：最小变更面、不引入新功能与接口变更；必要时启用特性开关进行隔离。
3. 校验与预发布
   • 完整的单元/集成/回归测试覆盖包含此次变更影响面。
   • 打预发布标签：vYYYY.MM.Px-rc.1；在预生产完成针对性验证与回归。
4. 发布与监控
   • 通过评审后打 GA 标签：vYYYY.MM.Px；采用快速灰度并设置缩短观察窗口的指标闸门。
   • 同步更新发布说明（仅修复项与影响说明）。
5. 回灌与合规
   • 将修复变更合并回 main 与未关闭的 release/YYYY.MM 分支，防止回归。
   • 更新安全公告、CVE 记录（如适用）、依赖清单与合规档案。
6. 回滚策略
   • 失败即刻回滚至上一个 GA 标签（如 vYYYY.MM 或 vYYYY.MM.P(x-1)），并触发事后复盘。
   • 对涉及数据变更的补丁必须具备可逆迁移或双写/影子表方案。

版本归档规范

• 归档内容（每个 GA/RC 必备）：
  • 源码标签与提交哈希、构建产物、构建脚本与参数、哈希校验。
  • 测试报告（覆盖率、关键用例结果、性能基线）、安全扫描报告、许可证清单。
  • 依赖锁定文件与软件物料清单（SBOM）、配置差异说明、迁移脚本与回滚脚本。
  • 发布说明、已知问题与临时规避策略、变更审阅记录与签署记录。
• 保留与访问控制：
  • 一般版本保留不少于24 个月，年度 LTS（如启用 maint/YYYY）保留36 个月。
  • 归档存储需具备防篡改与访问审计；GA 标签与产物要求不可变。
• 变更日志管理：
  • 按结构化提交自动生成并人工校订；分类包含 feat/fix/perf/refactor/docs/test/chore、弃用与破坏性变更。
  • 提供组件级与整包级两套视图，支持按子系统筛选。
• 依赖管理与冲突解决建议：
  • 统一使用锁定文件与最小可复现构建；拒绝浮动版本范围（如 ^、~）进入 release 与 hotfix。
  • 定期（每月度版前）执行依赖健康体检：安全、兼容、体积与性能评估。
  • 冲突处理优先级：对齐平台推荐版本 > 微升/回退到已验证版本 > 受控覆盖；所有覆盖须登记风险与回滚方案。
  • 对外 SDK/集成点需标注支持的最小/最大 API 级别与对应 vYYYY.MM 兼容矩阵。
• 弃用与支持策略：
  • 发布时附带生效与弃用时间线（至少提前两个周期告知）。
  • 明确支持窗口：当前月度版本 + 上一月度版本 + 最近一个 P 修订；LTS 依据 maint/YYYY 另行规定。

以上规范确保 Lumen 日历协作App 在采用日历化版本控制的同时，维持清晰的兼容边界、稳定的计划发布节奏与可审计、可回滚的工程保障链路。

版本控制概述

• 适用范围：本指南适用于 Nebula 物联网网关固件的源代码、固件镜像、OTA 包、发布说明及相关构建产物的版本管理、分支策略与发布流程。
• 目标用户：面向开发团队、测试团队、运维团队，确保版本可追溯、可审计、可回滚、可自动化。
• 核心原则：
  • 使用**语义化版本控制（SemVer）+ 发布序列号（Serial）**的复合方案：人类可读版本用于沟通与文档，单调递增的序列号用于设备侧升级判定与回滚控制（序列版本控制）。
  • 所有发布使用不可变、带签名的标签，所有制品具备哈希与签名，并保留完整SBOM 与测试记录。
  • 分支策略采用主干开发 + 发布分支 + 支持分支 + 热修复分支的稳定实践，配合短期代码冻结与候选版本（RC）流程。
  • 发布节奏为按需发布，配合分级/金丝雀分发与健康度指标监控，支持快速回滚与热修复。

版本号命名规范

• 版本标识由两类构成：
  1. 人类可读的语义化版本（SemVer）
  2. 设备判定使用的发布序列号（Serial）
• 标准格式（字符串组合示例，严格字符集保证可解析）：
  • 完整版本串：Nebula-v<MAJOR>.<MINOR>.<PATCH>[-<PRERELEASE>.<N>][-HW<NN>][-<REGION>][+<BUILD>] S< SERIAL >
  • 示例：Nebula-v2.3.0-rc.1-HW03-CN+20251212T1030 S345
• 字段定义与语义：
  • MAJOR（主版本）：引入不兼容变更（配置、通信协议、OTA 升级协议或公有 API 变更）。设备如需跨主版本升级，必须满足兼容性前置条件与迁移脚本。
  • MINOR（次版本）：向后兼容的新功能、支持新硬件变体、非破坏性配置扩展。
  • PATCH（修订版本）：向后兼容缺陷修复、性能优化与安全更新，不改变已公开行为。
  • PRERELEASE（预发布）：alpha、beta、rc，用于内测/灰度，不用于生产广域推送。rc为发布候选，功能冻结，仅接受阻断性缺陷修复。
  • BUILD（构建元信息）：构建时间戳或提交摘要，便于定位，但不影响版本排序。
  • HW/REGION（硬件/区域变体）：硬件修订号、区域合规差异。不同变体的固件相互不可替换。
  • S（发布序列号）：整数，全局单调递增（同一产品线下所有变体共用一个递增序列），用于设备端升级决策。严禁复用或回退。
• 版本排序与判定：
  • 人类侧按 SemVer 排序；设备侧仅以序列号判定新旧（S346 > S345），预发布不推送至生产设备。
  • 如需回滚到旧代码，使用“向前回滚（Roll-forward rollback）”：发布一个更高序列号的新固件，内容回退到已知稳定版本（详见紧急修复流程）。
• 约束与规则：
  • 版本字符串字符集限制：[A-Za-z0-9.-+]，变体字段以短横线分隔，避免空格和中文字符出现在版本串。
  • 每次发布必须：同步更新版本文件、分配唯一序列号、生成对应OTA 清单（含版本、序列号、哈希、签名、尺寸、最小引导程序版本、硬件/区域约束）。
  • 预留保留字：alpha、beta、rc，禁止用于其他语义。

分支管理策略

• 分支模型：主干开发（main） + 发布分支（release/x.y） + 支持分支（support/x.y） + 功能分支（feature/*） + 热修复分支（hotfix/x.y.z）
  • main：始终可构建、可回归、可随时切发布分支；启用受保护分支策略（评审/状态检查/线性历史）。
  • feature/：短生命周期（<= 2 周），从 main 派生；合并回 main 前需评审与全量 CI 通过；优先使用rebase 或 squash 合并*保持历史清晰。
  • release/x.y：代码冻结窗口内创建，用于该次发布的稳定化与 RC；仅允许修复类型变更（fix/perf/security/chore-doc），需双人评审。
  • support/x.y：对应已发布的次版本长期维护线（LTS/维护期内），仅接受安全修复与关键缺陷修复。
  • hotfix/x.y.z：从对应发布标签或支持分支分出，用于紧急修复（高危漏洞/大面积故障）；合并回 release/support 和 main，保持版本线一致。
• 标签与签名：
  • 使用注解标签（annotated）+ 签名标记每个 RC 与正式版本：vMAJOR.MINOR.PATCH[-PRERELEASE] S<SERIAL>
  • 标签不可变更；如撤回（yank），新增“撤回公告”并在归档中标注风险。
• 提交信息规范（Conventional Commits 子集）：
  • 类型：feat（特性）、fix（修复）、perf（性能）、security（安全）、refactor、docs、test、build、ci、chore、revert
  • 必要时在消息体中引用变更影响范围、测试覆盖、回滚指引。
• 冲突与回合并规则：
  • feature 分支在合并前与 main rebase，解决冲突；禁止将 main 反向合并进 feature 后再提交。
  • release 分支只从 main 单向切出；修复先合入 release，再cherry-pick回 main（确保主干不丢补丁）。
  • hotfix 优先面向生产受影响版本线，随后双向回补 main 与其他维护分支。
• 依赖管理与版本锁定：
  • release/support 分支必须冻结依赖（锁文件/哈希钉住），变更需评审与合规扫描。
  • 驱动/内核/协议栈等关键依赖采用最小可行升级策略，避免跨大版本引入不确定性。
  • 外部二进制依赖需提供校验哈希与来源白名单。

版本发布流程

1. 规划与代码冻结
   • 明确发布范围、风险分级、回滚策略、目标设备批次与渠道（内测/灰度/稳定）。
   • 从 main 创建 release/x.y 分支并进入代码冻结：仅允许修复类变更。
2. 版本与序列号分配
   • 在 release 分支中更新版本文件至 MAJOR.MINOR.PATCH-rc.1，由发布经理分配唯一序列号 S（从发布序列登记簿申请）。
   • 生成初版 OTA 清单（草案），钉住依赖，输出 SBOM。
3. 构建与签名
   • 产出固件镜像、OTA 包、调试符号、SBOM，计算哈希并进行制品签名。
   • 启动全量 CI/CD：静态检查、单元/集成、协议兼容、存储/电源异常注入、内存/线程/时序分析、硬件在环（HIL）、升级/回滚演练（A/B 分区/健康检查）。
4. 候选版本（RC）验证
   • 标记 vMAJOR.MINOR.PATCH-rc.N S<serial>，发布至内测渠道与实验室设备。
   • 测试团队执行回归矩阵与合规校验（含许可证合规与安全扫描），问题以缺陷单跟踪；必要时递增至 rc.(N+1)。
5. 准入评审（Go/No-Go）
   • 评审项：关键用例通过率、性能回归阈值、崩溃率、升级成功率、功耗与温度稳定性、安全问题清零、文档完备性。
   • No-Go 触发时：修复后重走 RC 验证。
6. 正式发布与标记
   • 将版本更新为 MAJOR.MINOR.PATCH，更新OTA 清单并二次校验哈希/签名。
   • 创建并签名标签：vMAJOR.MINOR.PATCH S<serial>，生成发布说明（含破坏性变更、升级指引、风控标签）。
7. 分级/金丝雀发布
   • 按 1%→10%→25%→100% 渐进推送，观察窗口内监控指标：崩溃率、连接稳定性、资源占用、健康检查回退率、告警基线。
   • 任一指标越阈触发自动暂停和回滚预案（见紧急修复/回滚）。
8. 发布沟通与交接
   • 面向开发/测试/运维的发布通告：版本号、序列号、变更摘要、已知问题、回滚方式、支持窗口。
   • 更新运行手册与告警规则；将产出归档（详见版本归档规范）。
9. 发布后动作
   • 将 main 版本号切至下一个开发周期（例如 MAJOR.MINOR+1.0-alpha.0）。
   • 依据策略建立或更新 support/x.y 分支进入维护期。

安全与合规必选项：

• 所有发布制品必须签名；密钥严格保管并定期轮转（双人复核）。
• 构建需可复现：记录编译器版本、构建脚本、依赖锁定与环境指纹。
• 安全扫描（SCA/漏洞）与许可证合规报告必须随版本归档。

紧急修复流程

1. 触发条件与分级
   • 高危安全漏洞、广域功能中断、数据一致性风险或监管合规紧急要求。
2. 分支与修复
   • 自受影响版本的标签或 support/x.y 拉出 hotfix/x.y.z；仅纳入最小修复集，禁止引入新特性。
   • 增量测试覆盖受影响模块与升级/回滚路径，完成同级别安全与合规校验。
3. 版本与序列号
   • 递增PATCH版本并分配新的序列号（S 严格递增），例如 v2.3.1 S346。
   • 生成 RC（可选）并快速验证关键路径，通过后转为正式版。
4. 加速发布与风控
   • 缩短金丝雀窗口（如 5%→50%→100%，每阶段至少满足最小健康观测周期）。
   • 强化监控与告警阈值；若指标恶化立即暂停并执行回滚。
5. 回合并与善后
   • 将修复cherry-pick回 release/support 与 main，确保版本线一致。
   • 输出事后分析（RCA）、预防措施与测试用例补充。

回滚机制（两种）：

• 自动回退（设备侧健康检查 + A/B 分区）：升级后 N 次健康检查失败即切回上一个槽位。
• 向前回滚（Roll-forward rollback）：如果需要回到旧代码，但设备只接受更高序列号，则发布一个更高序列号的新固件，其代码基于已知稳定版本；例如用 v2.3.2 S347 承载 v2.3.0 的稳定内容与必要兼容补丁。避免通过降低序列号进行“降级”，以免引发安全与一致性风险。

版本归档规范

• 归档内容清单（每个发布/RC 必备）：
  • 签名标签与提交哈希、版本元数据（SemVer、序列号、变体、渠道）。
  • 构建产物：固件镜像、OTA 包、调试符号、安装/升级脚本、校验哈希、签名。
  • SBOM 与许可证合规报告，第三方依赖清单、来源与哈希。
  • 测试与验证报告：单元/集成/HIL/性能/升级回滚演练/金丝雀观测数据。
  • 发布说明与已知问题、升级与回滚指引、受影响范围与风控标签。
  • OTA 清单（机器可读）：版本、序列号、哈希、签名、尺寸、最小引导程序版本、硬件/区域约束、渠道策略。
• 序列号登记簿
  • 维护全局唯一序列号表：序列号→版本、变体、发布日期、负责人、撤回状态。
  • 任何撤回（yank）须保留记录并在 OTA 服务端禁止新设备拉取。
• 保留策略与可复现
  • 生产发布与其依赖工件至少保存 5 年（或满足更严格合规要求）。
  • 记录完整构建环境指纹，确保可复现构建与审计。
• LTS/维护与 EoL
  • 定义每个次版本的维护窗口（例如 12 个月）与安全支持政策。
  • 发布 EoL 公告：停止维护日期、替代版本、升级路线。
• 访问与权限
  • 归档库只读、最小权限访问；涉及签名密钥材料的存储需使用安全设施、双人审批导出。
• 撤回与重发布
  • 撤回版本保留归档但标记“不可分发”；若需重发布，使用新序列号并在发布说明中指明替代关系。

附：团队协作要点与检查清单

• 开发：
  • 提交遵循规范；功能分支小步快跑；在 main 合并前确保编译与测试通过。
• 测试：
  • RC 阶段执行覆盖矩阵；对升级/回滚进行必测；出具 Go/No-Go 建议。
• 运维：
  • 严格按分级发布；监控指标与阈值按版本说明更新；遇警戒阈值立即冻结分发并按预案回滚。
• 必做验证（每次正式发布）：
  • 构建可复现、制品签名、SBOM 完整、关键回归通过、升级/回滚演练通过、序列号已登记且唯一、标签已签名且归档完毕。