分支与 Tag 管理

本文档定义公司全部产品研发的分支模型、命名规范、生命周期管理与 Tag 规范，适用于所有前后端开发人员。

• 与现有产物的关系（以下路径取自 EasyPro 仓库，其他产品参照同理）：

- data/sql/：初始建库脚本（多数为空占位文件），已迁移为 sql/release/2.1.0/ 全量建库。

- doc/驱动设计文档/modbus...升级SQL.sql：已实践的「游标遍历 + 幂等保护」增量脚本范式，本规范将其作为 SQL 增量脚本标准模板（现已汇总为 sql/release/2.1.1/3_modbus.sql）。

- doc/智问/、doc/驱动设计文档/：散落的 SQL 脚本，已按分支镜像规则归入 sql/ 对应目录（详见 06·SQL 版本化）。

本项目采用发布版本化部署（每个版本打成集成安装包，本地化部署到项目现场），因此沿用「长期版本分支」模式，而非纯 GitFlow 或 GitHub Flow：

与 GitFlow 的取舍：

• 保留 GitFlow 的「长期 release 分支 + 现场修复回流」思想，契合现场版本化部署。
• 不设独立 develop 分支（项目规模与团队节奏不需要集成分支，release 分支直接承担集成职责）。

通用格式：<前缀>/<版本号>/<语义>，其中版本号为语义化版本点分（如 2.1.1，不带 v 前缀）。

规则细则：

• feature/ / hotfix/ / custom/ / dev/ 必须带版本号，标明基于哪个版本（多版本并行下避免归属不明）。
• feature 只面向未发布版本：已打 tag 的版本禁止新开 feature/ 分支；已发布版本的演进只有两条路：不改库的 hotfix（03·规则三）或 custom 定制（改库需求的唯一出口）。
• 语义部分中文或英文均可：中文用简明短语（如 knx隧道假死优化），英文用小写 + 连字符（如 bacnet-cov）；禁止空格与特殊符号；应体现「功能/问题」，而非人名。
• dev/ 版本号可省略（个人临时分支、基点随意），但带版本号便于归类时仍推荐。
• 前端工程同样遵守本表；如需区分前后端，可在语义部分加 -fe 后缀（如 feature/2.1.1/optiview-sso-fe）。
• 子产品（产品线）用四段式：<前缀>/<产品代号>/<版本号>/<语义>（如 feature/eos/2.1.0/择机算法），产品代号占第二段、版本号降至第三段；主产品视为默认产品线，省略产品段、仍用三段式（详见产品线分支节）。
• 避免与版本主线节点同名：版本号作为独立 / 段时，不能与同前缀下的 release 节点同名（即 release/2.1.1 与 release/2.1.1/xxx 不能并存）。由于版本主线用 release/2.1.1、其余前缀各异，实际不冲突。

创建基点规则：

使用期限：

• feature/ ≤ 2 周，超期需拆分。
• dev/ ≤ 3 天，仅作临时实验。
• hotfix/ 现场验证通过、双向回流完成后即删除，不长期保留。
• custom/ 可长期存在（持续服务某客户），但需在 doc/ 备案其定制内容。
• line/ 主线及产品线内分支随子产品生命周期长期存在；新建产品线须先在 doc/规则/产品线登记.md 登记（详见产品线登记）。

清理流程：

# 1. 删除本地已合并分支（保留 main 与所有 release/）
git branch --merged | grep -vE '^\*|main|release/' | xargs -n1 git branch -d

# 2. 清理远程已删除分支的本地引用
git fetch -p

# 3. 删除远程已合并分支（需人工确认）
git push origin --delete <branch-name>

# 建议每月执行一次清理，负责人统一处理

• 格式：统一 vX.Y.Z（语义化版本 SemVer）；维护性微版本用四段 vX.Y.Z.N（如 v2.1.0.1，见 03·规则五）。tag 段数即类型：三段 = 正式版，四段 = 微版本。
版本号的含义与变化规则
v
前缀
2
MAJOR
不兼容大改
.
1
MINOR
新功能
.
0
PATCH
补丁修复
版本号变化示例
v2.1.0
v2.1.1
PATCH：修了个 bug
v2.1.1
v2.2.0
MINOR：新增了功能
v2.2.0
v3.0.0
MAJOR：架构大改，不兼容旧版
tag 号 = 安装包版本号 · 版本发布当天打 tag · 必须用 annotated tag

- MAJOR：不兼容的大版本（2.x → 3.x）

- MINOR：新功能版本（2.1.x → 2.2.0）

- PATCH：补丁版本（2.1.0 → 2.1.1）

• 打 tag 时机：版本发布的当天，tag 号与安装包版本号完全一致。
• 必须用 annotated tag（带说明信息）：

git tag -a v2.1.0 -m "Release v2.1.0

功能：
- 新增 BACnet IP 驱动 COV 订阅
- 智问大模型配置

修复：
- Modbus 写功能码切换
- COV 订阅判断逻辑"

• 废弃混用：当前存在的 2.0.0（无 v）、v2.0.0-pre、ems-lite_V1.0.0 应统一为 vX.Y.Z 格式；pre-release 用 vX.Y.Z-rc.N（如 v2.1.0-rc.1）。
• 子产品 tag 格式：<产品代号>-vX.Y.Z（如 EOS 用 eos-v2.1.0），主产品 tag 格式 vX.Y.Z 不变。注意子产品 hotfix/<产品>/、custom/<产品>/ 的拉取基点是其产品线主线头（line/<产品>/<版本>），tag 用于标记发布版本（详见产品线命名格式）。

除主产品外，公司还有若干独立子产品：节能 EOS、轻量版（ems-lite）、碳排（carbon）等。它们有三个共同点：

• 基于主产品某个版本分叉而来，但长期独立演进、不合并回主版本；
• 有自己的多版本节奏（基于 2.1.0 → 演进到自己的 2.1.1 → ……）；
• 内部同样需要 feature/、hotfix/ 这套二级分支。

现有的 custom/（见 03-合并回流与定制隔离）是为单客户交付设计的，承载不了子产品的二级结构与多版本演进；而让它们裸名（reduceEnergy、ems-lite、carbon）与版本分支同处一层，又会污染命名空间。为此引入产品线分支 line/。

核心思路是在主产品三段式的第二段插入产品代号，前缀不变，这样前缀仍表达「做什么」，第二段表达「给哪个产品」，两个维度正交。

• 产品代号英文小写（eos / lite / carbon），全局唯一，在 doc/规则/产品线登记.md 备案后使用。
• 语义段复用 §2.2 规则；产品代号不计入语义段。
• 产品线主线 line/<产品>/<版本> 长期保留，地位等同 release/<版本>。
• 子产品版本号二选一，登记时定死（一条产品线只允许一种）：独立编号（推荐，子产品有自身发布节奏时）主线用双版本段 line/<产品>/<基线版本>-<自身版本>（如 line/eos/2.1.0-1.0.0，读作「基于 2.1.0 的 EOS 1.0.0」，基线在前、创建后不变）；同号（完全跟随主产品节奏时）基线=自身，单段即可，如 line/eos/2.1.0。
• 子支线与交付物只带自身版本（基线由所属主线决定）：feature/eos/1.1.0/<语义>、sql/line/eos/1.0.0/、sql/tag/eos/1.0.0/；tag 用自身版本（如 eos-v1.0.0），annotated 说明中记录对应基线。
• 大版本换基 = 新主线分支：下个自身大版本若换到新主产品基线（如 2.1.1），新建 line/eos/2.1.1-2.0.0（旧主线保留），登记表更新并在备注追加换基记录；日常下行同步是 merge，不改基线段。
• 维护性微版本 tag 一律四段：子产品 eos-v1.0.0.1、主产品 v2.1.0.1——三段 = 正式版，四段 = 微版本，看段数即知类型；子产品正式小版本仍用修订位递增（1.0.0 → 1.0.1，三段 tag）。
• Tag 格式 <产品>-vX.Y.Z（如 eos-v2.1.0），主产品 tag 不变。

• ① 下行同步（主线→子产品）：允许、选择性。子产品负责人按需 git merge 或 rebase 主产品通用更新。
• ② 上行回流（子产品→主线）：默认禁止（与 custom/ 同思想）。
• ③ 例外：通用修复回流。子产品上修了主产品也存在的通用 bug，负责人判断后 cherry-pick 单个提交回主产品 release/——人工判断、逐提交、严禁整分支合并。
• ④ 子产品内部双向回流。hotfix/eos/2.1.0/xxx 须回流到 line/eos/2.1.0 + 下个 line/eos/2.1.1，规则同主产品 hotfix，只是 release/ 换成 line/eos/。
• ⑤ 子产品内的客户定制（custom/eos/...）双重不回流。既禁回 line/eos/，也禁回主产品 release/；交付方式为从该 custom/eos/ 单独打安装包。

# ① 下行同步：把主产品通用更新搬进子产品
git checkout line/eos/2.1.0
git merge release/2.1.0          # 或按需 cherry-pick 特定提交

# ③ 例外：子产品上的通用 bug 回流主产品（逐提交，人工确认）
git checkout release/2.1.1
git cherry-pick <eos-通用修复-commit>

# ④ 子产品 hotfix 双向回流
git checkout line/eos/2.1.0 && git merge hotfix/eos/2.1.0/xxx
git checkout line/eos/2.1.1 && git merge hotfix/eos/2.1.0/xxx
git branch -d hotfix/eos/2.1.0/xxx

每个子产品在 doc/规则/产品线登记.md 备案：产品代号、中文名、基线主产品版本、维护人、当前版本、产品线主线分支、交付现场、文档链接。