首页
/ LobeHub 补丁版本（Patch Release）发布全场景指南：每周发布、Bug 热修复、新模型上线与数据库迁移

LobeHub 补丁版本（Patch Release）发布全场景指南：每周发布、Bug 热修复、新模型上线与数据库迁移

2026-09-06 18:38:12作者：庞眉杨Will
lobehub
🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.
项目地址：https://gitcode.com/GitHub_Trending/lo/lobehub

本文档面向维护 LobeHub（LobeChat）版本流程的开发者与 AI Agent，系统讲解补丁版本发布的四类典型场景——每周发布、紧急 Bug 热修复、新模型上线与数据库 Schema 迁移，覆盖从分支创建、变更集扫描、changelog 撰写到 PR 合入后自动打 tag 的全链路。读完本文，你将掌握各场景下分支命名、命令行操作与发布文案的硬性规范，并理解 auto-tag-release 自动发布流水线的触发判定与版本递增原理。

一、机制总览：补丁版本如何被自动递增

在 LobeHub 的版本体系中，开发主线是 canary，日常开发全部在 canary 上进行；发版时将 canary 合入 main，合入后由 CI 流水线自动完成打 tag、升版本、创建 GitHub Release，并把 main 同步回 canary。

所有的 Patch Release 场景都会自动递增 patch 版本号（例如 2.1.31 → 2.1.32），因此 PR 标题无需包含版本号。这与 Minor Release（功能迭代，约每 4 周一次，版本号手动写入 PR 标题 🚀 release: v{x.y.0}）形成两条明确的分工，可参见发布路由表 version-release/SKILL.md 与 minor-release.md。

四种补丁发布场景及其共性特征归纳如下：

场景 源分支 PR 标题要求 版本号来源
每周发布（Weekly Release） canary 自定义（如 🚀 release: {YYYYMMDD}） 合入后自动 patch +1
Bug 热修复（Hotfix） main gitmoji 前缀（如 🐛 fix: ...） 合入后自动 patch +1
新模型上线（New Model Launch） 任意正常功能分支 ✨ feat: / 💄 style: 等触发前缀 合入后自动 patch +1
数据库 Schema 迁移（DB Migration） main（cherry-pick） 👷 build: {migration description} 合入后自动 patch +1

自动发布触发规则：从工作流源码看判定优先级

判断一次合入 main 的 PR 是否触发发布、以及触发哪种发布，逻辑全部落在 .github/workflows/auto-tag-release.yml 中，判定优先级如下：

  1. Minor Release（精确版本）：PR 标题匹配 🚀 release: v{x.y.z}，直接采用标题中的版本号。
  2. Patch Release（自动 patch +1），按优先级继续判定：
    • 分支名优先：PR 头分支为 hotfix/* 或 release/* 时直接触发，绕过标题检测（workflow 源码 中注释 title gate bypassed）；
    • 标题前缀兜底（legacy 行为）：标题以 style/feat/fix/refactor/hotfix/build 前缀（含 gitmoji 版本，如 💄 style:、✨ feat:、🐛 fix:、♻️ refactor:、🩹 hotfix:、👷 build:）开头时触发（workflow 源码）。
  3. 不触发：docs、chore、ci、test 等不符合以上条件的前缀合入 main 后不会触发任何发布。

patch 版本的解析同样由流水线完成（workflow 源码）：先读取 package.json 中的当前版本并 semver -c 归一到稳定基线（例如 2.0.0-beta.1 → 2.0.0），再执行 semver -i patch 得到下一个补丁版本（2.0.0 → 2.0.1），即预发布版本也会被正确换算为稳定的下一个 patch 版本。合入后自动化动作依次为：

  1. 提交 🔖 chore(release): release version v{x.y.z} [skip ci] 更新 package.json；
  2. 在版本提交（而非 PR merge commit）上创建带注解的 tag v{x.y.z}；
  3. 创建 GitHub Release；
  4. dispatch sync-main-to-canary 工作流将 main 同步回 canary（workflow 源码）。

分支基座预检（适用所有类型）：每周发布（release/weekly-*）必须从 canary 拉分支；其余 release/hotfix 分支必须基于 main，可用 git merge-base --is-ancestor main <branch> && echo OK 校验，基座错误则重建分支。详见 version-release/SKILL.md 的 Precheck 说明。

二、场景一：每周发布（Weekly Release，canary → main）

每周发布是最常见的发布类型，把 canary 上累积一周的变更收集并发布到 main。

Step 1：从 canary 创建发布分支

git checkout canary
git pull origin canary
git checkout -b release/weekly-{YYYYMMDD}
git push -u origin release/weekly-{YYYYMMDD}

Step 2：扫描变更并撰写 changelog

先计算 main 上的上一个 tag，绝不复用上一周发布的 tag —— 因为两周之间可能有直接合入 main 的 hotfix 被发布，复用旧 tag 会漏掉这些版本（这正是热修复通过 sync-main-to-canary 回流到 canary 后，每周基线必须以 main 上最新 semver tag 为准的原因）：

git fetch origin main canary --tags
PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --oneline --no-merges
git diff "$PREV_TAG...origin/release/weekly-{YYYYMMDD}" --stat

随后遵循 release-notes-style.md 中「Computing Inputs（Hard Rules）」章节推导 PR 引用、指标与贡献者。其中最核心的硬性规则是：

  • PR refs 必须来自 commit subject，绝不来自描述：用 git log ... --pretty=format:'%s' --no-merges | grep -oE '\(#[0-9]+\)$' | sort -u 生成规范集合，正文中出现的每一个 (#XXXX) 都必须存在于该集合中。凭记忆推断的 PR 号是此技能第一大失败模式；
  • 指标必须来自 git 计数：PR 数、commit 数、贡献者数（需过滤 lobehubbot、renovate[bot]）分别通过 wc -l、git log、sort -u 计算，无法可靠推导的数字宁可省略，绝不猜测；
  • 作者以 GitHub handle 呈现：git %an 是提交者显示名而非 handle，需用 gh pr view "$PR_NUMBER" --json author --jq '.author.login' 解析确认；
  • 发布前强制校验：将正文中引用的 PR 与规范集合做差集（comm -23），输出必须为空，非空即代表正文引用了未在本区间合入的 PR。

每周发布的 changelog 属于 Long-Form（长格式），完整骨架见 changelog-example/weekly-release.md：头部为发布日期与 Since previous release 指标行，随后是 3–8 条 Highlights 要点，再按核心架构、平台集成、CLI 与体验、工具链、安全与可靠性等领域分组（## 🏗️ Core Agent & Architecture、## 📱 Platforms / Integrations 等），最后以 Contributors 列表与 **Full Changelog**: <prev>...<current> 收尾。

Step 3：创建合入 main 的 PR，changelog 作为 PR body

gh pr create \
  --title "🚀 release: {YYYYMMDD}" \
  --base main \
  --head release/weekly-{YYYYMMDD} \
  --body-file changelog.md

Step 4：合入后

auto-tag-release 检测到 release/* 分支，自动 patch +1，无需任何手工操作。

三、场景二：紧急 Bug 热修复（Bug Hotfix）

紧急缺陷修复直接从 main 上发布，目标是单点回归、快速上线。

Steps

  1. 从 main 创建热修复分支
git checkout main
git pull --rebase origin main
git checkout -b hotfix/v{version}-{short-hash}
git push -u origin hotfix/v{version}-{short-hash}
  1. 创建合入 main 的 PR，标题使用 gitmoji 前缀（如 🐛 fix: description）。
  2. 撰写简短的热修复 changelog（模板见 changelog-example/hotfix.md），保持极简：
    • 一行 Hotfix Scope（回归范围，替代长格式的指标行）；
    • 1–3 条修复 bullet，每条按「症状 — 一句话说清修复」格式，附 (#PR)；
    • Upgrade 升级说明；
    • Owner 负责人。不写冗长的 root-cause 段落——根因分析放在 commit message 中。
  3. 合入后：auto-tag-release 检测到 hotfix/* 分支，自动 patch +1。

热修复 changelog 属于 Short-Form 变体，与长格式的关键差异（release-notes-style.md「Hotfix Variant」章节）为：不包含 Highlights、领域分组、Contributors 与 Full Changelog，不写 Since vX.Y.Z 指标行，整体应控制在一屏以内；Owner 只列一位作者，且放在 ## 👥 Owner 下而非扁平 handle 列表。

Owner 解析规则：热修复负责人应使用实际 PR 作者，通过 gh pr view <number> --json author --jq '.author.login' 获取，绝不可硬编码用户名（这一点同样适用于 DB 迁移场景）。

一键脚本：bun run hotfix:branch

发布脚本已注册在 package.json：

bun run hotfix:branch

其真实入口为 scripts/hotfixWorkflow/index.ts，从源码看它完成了热修复全流程的自动化（对当前分支状态做智能分流）：

  • 仅在 main 或 hotfix/* 分支上可运行，否则报错退出（脚本逻辑）；
  • 在 main 上运行时：先 git pull --rebase origin main，读取 package.json 中的当前版本，用 semver 解析后取主版本三元组并 patch 递增（预发布版本也会归一为稳定 patch，如 2.0.0-beta.1 → 2.0.1，见 bumpPatchVersion），再取当前 HEAD 短哈希拼出分支名 hotfix/v{version}-{hash}（createHotfixBranchName），随后创建分支、推送远端、调用 gh pr create 以 --base main 创建标题为 🐛 hotfix: v{version} 的 PR；
  • 在已存在的 hotfix/* 分支上运行时：直接从分支名正则中提取版本号（extractVersionFromBranch），跳过建分支步骤，直接推送并提交 PR。

整个过程带交互确认与逐步 consola 日志，属于对上面手工命令的标准封装。

四、场景三：新模型上线（New Model Launch）

新 AI 模型或 Provider 支持通常由社区 PR 贡献，流程最简单。

工作原理

  • 社区贡献者提交形如 ✨ feat: add xxx model 或 💄 style: support xxx models 的 PR；
  • 这类 PR 标题前缀（feat / style）正落在 auto-tag 触发列表（见上文工作流源码的标题前缀判定 auto-tag-release.yml）中；
  • 无需特殊分支命名，也无需手工发布步骤 —— 合并 PR 即触发自动 patch +1。

当 Agent 参与时

若被要求为仓库添加模型支持，只需创建一个普通的 feature PR 即可。标题前缀会自动触发发布流程，不要额外创建 release/* 分支或手动处理版本号。

五、场景四：数据库 Schema 迁移（DB Schema Migration）

数据库 schema 变更需要独立发布，因为要面向自托管用户输出专门的迁移说明 changelog。

Steps

  1. 从 main 创建发布分支并 cherry-pick 迁移提交
git checkout main
git pull --rebase origin main
git checkout -b release/db-migration-{name}
git cherry-pick <migration-commit-hash>
git push -u origin release/db-migration-{name}
  1. 撰写迁移专属 changelog（格式见 changelog-example/db-migration.md），需说明：
    • 新增/修改/删除了哪些表、哪些列；
    • 迁移是否向后兼容；
    • 自托管用户需要执行的任何操作；
    • 迁移负责人：使用实际 PR 作者（通过 gh pr view <number> --json author --jq '.author.login' 或 git log 的提交作者获取），绝不可硬编码用户名。

迁移 changelog 在 release-notes-style.md「DB Migration Variant」中有固定的短格式结构：头部标题 + scope 行 → Migration overview（表/列变更）→ Operator impact（是否向后兼容、自托管用户需做什么）→ Rollback / backup note（如何恢复）→ ## 👥 Owner。迁移（尤其是新增表与索引这类 additive 变更）通常在应用启动时自动执行、标准部署路径无需手工 SQL，因此示例模板特别要求提醒运维选择低峰窗口并提前做备份快照（示例）。

  1. 创建合入 main 的 PR，迁移 changelog 作为 PR body：
gh pr create \
  --title "👷 build: {migration description}" \
  --base main \
  --head release/db-migration-{name} \
  --body-file changelog.md
  1. 合入后：auto-tag-release 检测到 release/* 分支，自动 patch +1。

从实现侧看，本仓库的数据库迁移遵循独立的 drizzle/db-migrations 工作流（参见 db-migrations 技能），发布环节只负责把已提交的迁移 cherry-pick 到 release 分支并产出面向运维的说明，二者职责清晰分离。

六、适用于所有类型的硬性规则与核查清单

硬性规则（来自 version-release/SKILL.md）

  • 不要手工修改 package.json 版本号 —— 由 CI 负责；
  • 不要手工创建 tag —— 由 CI 负责；
  • Minor PR 标题格式严格（🚀 release: v{x.y.z}）；
  • Patch PR 不需要显式版本号；
  • 发布信息必须事实准确：所有对比基线、PR 引用、贡献者列表都必须按 release-notes-style.md「Computing Inputs」章节从 git 推导，绝不凭记忆或描述编造指标与可用性声明。

撰写前的核查清单

每周/Minor（长格式）：

  • [ ] PREV_TAG 为 git describe --tags --abbrev=0 origin/main 得出的最新 semver tag，而非上一周 tag；
  • [ ] 正文每个 (#XXXX) 均出现在规范 PR 集合中（comm -23 差集为空）；
  • [ ] Since v… 指标行与 PR/贡献者计数和计算集合一致，**Full Changelog** 使用 $PREV_TAG；
  • [ ] 作者 handle 通过 gh pr view --json author 解析，而非直接使用 %an。

Hotfix（短格式）：

  • [ ] **Hotfix Scope:** 行替代指标行；
  • [ ] ## 🐛 What's Fixed 仅 1–3 条，每条 **<症状>** — <一句话修复>。(#PR)，PR 引用已验证真实存在并已合入；
  • [ ] ## ⚙️ Upgrade 写明自托管操作与云端的自动应用；
  • [ ] ## 👥 Owner 是单个 @handle（gh pr view 解析得出）；
  • [ ] 不含 Highlights / 领域分组 / Contributors / Full Changelog。

DB 迁移（短格式）：

  • [ ] 包含 Migration overview、operator impact（是否向后兼容）、rollback/backup 说明与 Owner。

更多长格式与短格式的选择依据（含各发布规模下 Highlights 条数建议）可查阅 release-notes-style.md 的「Release Size Heuristics」与「Quick Checklist」章节；发布 PR 的 GitHub Release 正文均可在 changelog-example 目录下找到可直接套用的规范模板。

lobehub
🤯 LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.
项目地址：https://gitcode.com/GitHub_Trending/lo/lobehub
登录后查看全文
热门项目推荐
相关项目推荐

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
855
1.34 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
589
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.73 K
docsdocs
暂无描述
Markdown
897
5.79 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.56 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
998
511
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
909
1.83 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313