mirror of
https://gitcode.com/JianFeeeee/HomeAgent.git
synced 2026-09-21 09:28:14 +00:00
docs(git): SDK 仓版本语义与发版联动，并明确 main 永不作发版分支
三条此前没写进规范、于是被我在实际操作中做错的规则： ## 一、SDK 版本号跟随核心的中版本，patch 位恒为 .0（新 §七.1） 整条核心 1.1.x 线共用 SDK 1.1.0；只有核心进入 1.2.0 这种中版本跃迁时 SDK 才升。 核心的 patch 位专用于 bugfix 与漏洞修复，这类改动不碰公开 SDK 接口，SDK 版本号 没有理由跟着动。 **为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix 就给 SDK 推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个 字都没变。让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在 为哪个中版本写插件」。 因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0）， 不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。§四 的措辞同步修正。 ## 二、beta 阶段不发 SDK（新 §七.2） 核心的 alpha/beta tag 不伴随 SDK 仓发版：SDK 仓在这一阶段不打 tag、不建 release。 **为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版， 插件开发者会照着一个还会变的接口写代码——那是无效开发。接口没定就没有可依赖的 契约，发出去的版本号是一个假承诺。 这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。主仓用 `replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored SDK 源码， 那是构建机制决定的，不在约束范围内。 核心打**正式** tag 时 SDK 才随之发版（§七.3）：SDK 仓也有自己的 `release/vX.Y.x`， 定版为 `X.Y.0`，打 tag、建 release、传 5 平台 plugindev 产物。同一中版本内的后续 核心 patch 不重复发 SDK。 ## 三、main 永远不是发版分支（补进 §四） 版本号 bump、打 tag、构建产物、上传附件，全部只在 `release/vX.Y.x` 上做。 **即使某个改动刚合进 main、即使 main 此刻可部署，也不从 main 打 tag。** main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。 这条本该是 §2.1「main 的 meta.Version 始终是下一个未发布版本」的直接推论，但 只写了状态、没写禁令，于是留下了「main 可部署 ⇒ 可以从 main 发版」的误读空间。 §三 的分支表补上 main 现值 `1.2.0` 与 1.1.x 线的 tag 历史，让路牌语义有实例可对。 ## 四、公开接口改动是 feature，不是发布准备（补进 §六） 它必须走 `feature/xxx` → 合回 main → cherry-pick 到发布分支，不允许当成「发布 分支上的 bug 修复」直接提交进 release——发布分支冻结功能（§2.3），而接口是最 典型的功能面。§五 补上这条路径的命令示例，以及 SDK 仓同步发版的命令。
This commit is contained in:
JianFeeeee
@ -1,6 +1,6 @@
|
||||
# Git 分支管理规范
|
||||
|
||||
> 生效：2026-08-31，2026-09-04 修订（三级发布通道 + 单条发布分支）。
|
||||
> 生效：2026-08-31，2026-09-04 修订（三级发布通道 + 单条发布分支），2026-09-06 修订（SDK 仓版本语义与发版联动，见 §七）。
|
||||
> 适用：**本仓（TrueAgent/HomeAgent）与 third_party/homeagent-sdk（SDK 仓）**——两仓协作时分支策略必须一致，本规范两仓同用。
|
||||
> 核心原则一句话：**main 唯一长命、永远可部署；一切新工作在特性分支；一个中版本一条发布分支，alpha/beta/正式由 tag 区分；hotfix 只进发布分支并 cherry-pick 回 main。**
|
||||
|
||||
@ -83,6 +83,10 @@ main ──────────────── E ────────
|
||||
- alpha/beta 的构建产物**可以上传 release 附件**，但必须在 gitcode release 上勾选
|
||||
"预发布"标记，且发布说明首行标注通道与已知风险。
|
||||
- **beta 未清零的严重问题不得进正式**：正式 tag 意味着"我们认为它能上 24/7 现网"。
|
||||
- **发版动作只在发布分支上做**：版本号 bump、打 tag、构建产物、上传 release 附件，
|
||||
全部发生在 `release/vX.Y.x` 上。**main 永远不是发版分支**——即使某个改动刚刚合进 main、
|
||||
即使 main 此刻可部署，也不从 main 打 tag、不拿 main 的构建产物发布。
|
||||
main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。
|
||||
|
||||
### 5. hotfix（发布后发现的严重 bug）
|
||||
|
||||
@ -132,12 +136,21 @@ main ──────────────── E ────────
|
||||
|
||||
| 分支 | 状态 | 处理 |
|
||||
|---|---|---|
|
||||
| `main` | 含全部 hotfix（逐个 cherry-pick），`meta.Version` = 下一个未发布版本 | ✅ 保持 |
|
||||
| `main` | 含全部 hotfix（逐个 cherry-pick），`meta.Version` = 下一个未发布中版本（现为 `1.2.0`） | ✅ 保持 |
|
||||
| `release/v1.0.x` | 承载 v1.0.0 / v1.0.1 / v1.0.3 全部 tag | ✅ **由 `release/v1.0.1` 重命名而来**（2026-09-04） |
|
||||
| `release/v1.0.0` | `9b92a04`，已被 1.0.x 线完全包含（`merge-base --is-ancestor` 验证通过） | 🗑️ **已删除**（本地 + 远端），tag `v1.0.0` 保留全部历史 |
|
||||
| `release/v1.0.1` | 旧 patch 号命名 | 🗑️ **已重命名为 `release/v1.0.x`**（远端旧名删除） |
|
||||
| `feature/memory-media` | 记忆系统媒体（多模态）支持，进行中 | ⏳ 完成后合回 main 并删除 |
|
||||
| `feature/plugin-proc-migration` | 已合入 main（`525aa1f`） | ⏳ 待删（规范要求合回后删除） |
|
||||
| `release/v1.1.x` | 承载 v1.1.0 / v1.1.0-beta.1 / v1.1.1 全部 tag | ✅ 1.1 线的唯一发布分支 |
|
||||
|
||||
### SDK 仓（homeagent-sdk）
|
||||
|
||||
| 分支 | 状态 | 处理 |
|
||||
|---|---|---|
|
||||
| `main` | `meta.Version` = 下一个未发布中版本（现为 `1.2.0`） | ✅ 保持 |
|
||||
| `release/v1.1.x` | `meta.Version` = `1.1.0`，承载 tag `v1.1.0` | ✅ 与核心 `release/v1.1.x` 对应 |
|
||||
| `release/v1.0.0` | 旧 patch 号命名形态，内容已被 main 完全包含 | 📦 保留（供追溯 1.0 线构建） |
|
||||
|
||||
### 1.0.x 发布线 tag 历史
|
||||
|
||||
@ -149,6 +162,18 @@ main ──────────────── E ────────
|
||||
|
||||
> `v1.0.2` 未使用：该号从未发布也无 tag，留空以免与任何本地构建混淆。
|
||||
|
||||
### 1.1.x 发布线 tag 历史
|
||||
|
||||
| tag | 提交 | 通道 | SDK | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| `v1.1.0` | `579d7db` | 正式 | 1.0.0 | 记忆系统支持二进制多媒体节点（CAS 媒体存储 + L0/L2/L3 贯通） |
|
||||
| `v1.1.0-beta.1` | `7a57a14` | beta | 不发 | 打包链路验证（GUI 架构污染 + 空壳 node_modules）。按 §七.2，beta 不伴随 SDK 发版 |
|
||||
| `v1.1.1` | 见发布说明 | 正式 | **1.1.0** | 多模态贯通插件边界；SDK 首次随核心正式版发布 |
|
||||
|
||||
> `v1.1.0-beta.1` 的提交序在 `v1.1.0` **之后**（它多含一个打包修复），
|
||||
> 而 semver 预发布语义里 `1.1.0-beta.1 < 1.1.0`。这是「一条发布分支 + tag 区分通道」的
|
||||
> 已知代价：beta 是为验证**打包链路**而补打的，不代表源码更旧。发布说明里已注明。
|
||||
|
||||
---
|
||||
|
||||
## 四、现网部署与版本对应（运维纪律）
|
||||
@ -164,7 +189,7 @@ main ──────────────── E ────────
|
||||
- **改造期间现网不得部署 main 或 feature 的中间态**——只有发版才用发布分支的 tag。
|
||||
- alpha/beta tag 的产物**不上现网**（现网是 24/7 服务，预发布通道的存在就是为了不拿它冒险）。
|
||||
- 涉及 SDK 仓时：主仓 `go.mod` 的 `replace => ./third_party/homeagent-sdk` 指向本地 vendored 副本，
|
||||
发版前确认 vendored SDK 与 SDK 仓 release tag 一致（**两仓版本对齐是第一优先级**）。
|
||||
发版前确认 vendored SDK 与 SDK 仓 release tag 一致（**两仓中版本对齐是第一优先级**，见 §七）。
|
||||
|
||||
---
|
||||
|
||||
@ -199,6 +224,20 @@ git cherry-pick <修复①的sha> # ③ 只挑修复
|
||||
# 若有活跃 feature 分支，也 pick 过去
|
||||
git checkout feature/xxx && git cherry-pick <main 上那个 pick 的 sha>
|
||||
|
||||
# 公开 SDK 接口改动（feature，不是 hotfix）：先进 main，再 pick 到发布分支
|
||||
git checkout -b feature/sdk-xxx main
|
||||
# ... 改 third_party/homeagent-sdk/sdk/ 与内核桥接层 ...
|
||||
git checkout main && git merge --no-ff feature/sdk-xxx
|
||||
git checkout release/v1.1.x
|
||||
git cherry-pick <feature 的各 sha> # 只挑改动，不挑 main 的版本号
|
||||
git commit -am "chore(release): bump v1.1.1" # 发布分支自己的版本号
|
||||
git tag -a v1.1.1 -m "..."
|
||||
# SDK 仓同步（仅在核心打正式 tag 时，见 §七.2/§七.3）
|
||||
cd third_party/homeagent-sdk
|
||||
git checkout -b release/v1.1.x main
|
||||
git commit -am "chore(release): SDK 1.1.0（1.1.x 线全程共用）"
|
||||
git tag -a v1.1.0 -m "..."
|
||||
|
||||
# 发布分支退役（下个中版本发布后，可选）
|
||||
git branch -d release/v1.0.x # tag 已保存历史，删分支不丢东西
|
||||
```
|
||||
@ -211,3 +250,53 @@ git branch -d release/v1.0.x # tag 已保存历史，
|
||||
- `internal/sdk` **不受冻结约束**，可自由扩展；冻结只针对公开 SDK 接口（`third_party/homeagent-sdk/sdk/`）。
|
||||
- 若整改确需突破公开接口，走变更评审（见 `docs/zh/plugin-interface-matrix.md` §七），
|
||||
并同步 `SDKCompatibleVersion` 与 SDK 仓的 release tag。
|
||||
- **公开接口的改动本身是 feature，不是发布准备**：它必须走 `feature/xxx` → 合回 main 的路径，
|
||||
再 cherry-pick 到发布分支。不允许把接口新增当成"发布分支上的 bug 修复"直接提交进 release
|
||||
——发布分支冻结功能（§2.3），接口是最典型的功能面。
|
||||
|
||||
---
|
||||
|
||||
## 七、SDK 仓的版本语义与发版联动
|
||||
|
||||
### 1. SDK 版本号跟随核心的中版本，patch 位恒为 `.0`
|
||||
|
||||
| 核心版本 | 对应 SDK 版本 |
|
||||
|---|---|
|
||||
| 1.1.0 / 1.1.1 / 1.1.2 / … / 1.1.N | **1.1.0**（全线共用，不随核心 patch 变动） |
|
||||
| 1.2.0 起 | **1.2.0** |
|
||||
|
||||
- 核心的 patch 位（`x`）专用于 **bugfix 与漏洞修复**，这类改动不触碰公开 SDK 接口，
|
||||
因此 SDK 版本号没有理由跟着动。
|
||||
- **为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix 就把 SDK
|
||||
也推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个字都没变。
|
||||
让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在为哪个中版本写插件」。
|
||||
- 因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0），
|
||||
不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。
|
||||
|
||||
### 2. beta 阶段不发 SDK
|
||||
|
||||
- **核心的 alpha/beta tag 不伴随 SDK 仓发版**：SDK 仓在这一阶段**不打 tag、不建 release**。
|
||||
- **为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版，
|
||||
插件开发者会照着一个还会变的接口写代码——**那是无效开发**。接口没定就没有可依赖的契约，
|
||||
发出去的版本号是一个假承诺。
|
||||
- 这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。
|
||||
主仓 `go.mod` 用 `replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored
|
||||
SDK 源码，这是构建机制决定的，不在本条约束范围内。
|
||||
|
||||
### 3. 正式发布时 SDK 随核心一起发
|
||||
|
||||
核心打**正式 tag**（`vX.Y.Z`，无预发布后缀）时，SDK 仓同步执行：
|
||||
|
||||
1. SDK 仓也有自己的 `release/vX.Y.x`（与核心同名，一个中版本一条）；
|
||||
2. 在该分支上把 `meta.Version` 定为 `X.Y.0`；
|
||||
3. 打 tag `vX.Y.0`（首次进入该中版本时），并建 gitcode release；
|
||||
4. 上传 5 平台 plugindev 产物 + `SHA256SUMS`。
|
||||
|
||||
同一中版本内的后续核心 patch（1.1.1 → 1.1.2 …）**不重复发 SDK**——SDK 已经是 1.1.0，
|
||||
没有新东西要发。只有接口再次变化并进入下一个中版本时，SDK 才发 1.2.0。
|
||||
|
||||
### 4. 版本号在两仓 main 上的含义
|
||||
|
||||
两仓的 `main` 都遵守 §2.1：`meta.Version` 是**下一个未发布中版本**。
|
||||
所以在 1.1.x 线发布期间，两仓 main 上的值都是 `1.2.0`——它标记「main 正在积攒 1.2 的东西」，
|
||||
而不是「1.2.0 已经存在」。已发布的版本号一律看对应 `release/vX.Y.x` 分支与 tag。
|
||||
|
||||
Reference in New Issue
Block a user