version-release

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Version Release Workflow

版本发布工作流

Overview

概述

The primary development branch is canary. All day-to-day development happens on canary. When releasing, canary is merged into main. After merge,

auto-tag-release.yml

automatically handles tagging, version bumping, creating a GitHub Release, and syncing back to the canary branch.

Only two release types are used in practice (major releases are extremely rare and can be ignored):

Type	Use Case	Frequency	Source Branch	PR Title Format	Version
Minor	Feature iteration release	~Every 4 weeks	canary	`🚀 release: v{x.y.0}`	Manually set
Patch	Weekly release / hotfix / model / DB migration	~Weekly or as needed	canary or main	Custom (e.g. `🚀 release: 20260222` )	Auto patch +1

主开发分支为canary。日常开发工作均在canary分支进行。发布时，将canary分支合并至main分支。合并完成后，

auto-tag-release.yml

会自动处理标签创建、版本号更新、GitHub Release创建，以及将变更同步回canary分支。

实际使用中仅涉及两种发布类型（主版本发布极为罕见，可忽略）：

类型	适用场景	频率	源分支	PR标题格式	版本号规则
Minor	功能迭代发布	约每4周一次	canary	`🚀 release: v{x.y.0}`	手动指定
Patch	每周发布/热修复/模型/数据库迁移	每周或按需进行	canary或main	自定义（如 `🚀 release: 20260222` ）	自动补丁号+1

Minor Release Workflow

Minor Release工作流

Used to publish a new minor version (e.g. v2.2.0), roughly every 4 weeks.

用于发布新的次要版本（如v2.2.0），大约每4周进行一次。

Steps

步骤

Create a release branch from canary

bash

git checkout canary
git pull origin canary
git checkout -b release/v{version}
git push -u origin release/v{version}

Determine the version number — Read the current version from
```
package.json
```
and compute the next minor version (e.g. 2.1.x → 2.2.0)
Create a PR to main

bash

gh pr create \
  --title "🚀 release: v{version}" \
  --base main \
  --head release/v{version} \
  --body "## 📦 Release v{version} ..."

[!IMPORTANT]: The PR title must strictly match the
🚀 release: v{x.y.z}
format. CI uses a regex on this title to determine the exact version number.

Automatic trigger after merge: auto-tag-release detects the title format and uses the version number from the title to complete the release.

从canary分支创建发布分支

bash

git checkout canary
git pull origin canary
git checkout -b release/v{version}
git push -u origin release/v{version}

确定版本号 — 从
```
package.json
```
读取当前版本，计算下一个次要版本（如2.1.x → 2.2.0）
创建合并至main分支的PR

bash

gh pr create \
  --title "🚀 release: v{version}" \
  --base main \
  --head release/v{version} \
  --body "## 📦 Release v{version} ..."

[!IMPORTANT]: PR标题必须严格符合
🚀 release: v{x.y.z}
格式。CI会通过正则匹配该标题来确定具体版本号。

合并后自动触发：auto-tag-release会识别标题格式，并使用标题中的版本号完成发布流程。

Scripts

脚本

bash

bun run release:branch         # Interactive
bun run release:branch --minor # Directly specify minor

bash

bun run release:branch         # 交互式创建
bun run release:branch --minor # 直接指定次要版本

Patch Release Workflow

Patch Release工作流

Version number is automatically bumped by patch +1. There are 4 common scenarios:

Scenario	Source Branch	Branch Naming	Description
Weekly Release	canary	`release/weekly-{YYYYMMDD}`	Weekly release train, canary → main
Bug Hotfix	main	`hotfix/v{version}-{hash}`	Emergency bug fix
New Model Launch	canary	Community PR merged directly	New model launch, triggered by PR title prefix
DB Schema Migration	canary	`release/db-migration-{name}`	Database migration, requires dedicated changelog

All scenarios auto-bump patch +1. Patch PR titles do not need a version number. See

reference/patch-release-scenarios.md

for detailed steps per scenario.

版本号会自动进行补丁号+1更新。常见场景分为4种：

场景	源分支	分支命名规则	描述
每周发布	canary	`release/weekly-{YYYYMMDD}`	每周例行发布，将canary合并至main分支
漏洞热修复	main	`hotfix/v{version}-{hash}`	紧急漏洞修复
新模型上线	canary	社区PR直接合并	新模型上线，通过PR标题前缀自动触发
数据库Schema迁移	canary	`release/db-migration-{name}`	数据库迁移，需编写专用变更日志

所有场景均会自动将补丁号+1。Patch Release的PR标题无需包含版本号。各场景的详细步骤请参考

reference/patch-release-scenarios.md

。

Scripts

脚本

bash

bun run hotfix:branch # Hotfix scenario

bash

bun run hotfix:branch # 热修复场景专用

Auto-Release Trigger Rules (auto-tag-release.yml)

自动发布触发规则（auto-tag-release.yml）

After a PR is merged into main, CI determines whether to release based on the following priority:

当PR合并至main分支后，CI会根据以下优先级判断是否触发发布：

1. Minor Release (Exact Version)

1. Minor Release（指定版本）

PR title matches

🚀 release: v{x.y.z}

→ uses the version number from the title.

PR标题匹配

🚀 release: v{x.y.z}

→ 使用标题中的版本号进行发布。

2. Patch Release (Auto patch +1)

2. Patch Release（自动补丁号+1）

Triggered by the following priority:

Branch name match:
```
hotfix/*
```
or
```
release/*
```
→ triggers directly (skips title detection)

Title prefix match: PRs with the following title prefixes will trigger:

```
style
```
/
```
💄 style
```
```
feat
```
/
```
✨ feat
```
```
fix
```
/
```
🐛 fix
```
```
refactor
```
/
```
♻️ refactor
```
```
hotfix
```
/
```
🐛 hotfix
```
/
```
🩹 hotfix
```
```
build
```
/
```
👷 build
```

按以下优先级触发：

分支名称匹配：
```
hotfix/*
```
或
```
release/*
```
→ 直接触发（跳过标题检测）

标题前缀匹配：包含以下前缀的PR会触发发布：

```
style
```
/
```
💄 style
```
```
feat
```
/
```
✨ feat
```
```
fix
```
/
```
🐛 fix
```
```
refactor
```
/
```
♻️ refactor
```
```
hotfix
```
/
```
🐛 hotfix
```
/
```
🩹 hotfix
```
```
build
```
/
```
👷 build
```

3. No Trigger

3. 不触发发布

PRs that don't match any of the above conditions (e.g.

docs

chore

ci

test

prefixes) will not trigger a release when merged into main.

不符合上述任何条件的PR（如标题前缀为

docs

、

chore

、

ci

、

test

），合并至main分支时不会触发发布。

Post-Release Automated Actions

发布后自动操作

Bump package.json — commits

🔖 chore(release): release version v{x.y.z} [skip ci]

Create annotated tag —
```
v{x.y.z}
```
Create GitHub Release
Dispatch sync-main-to-canary — syncs main back to the canary branch

更新package.json版本号 — 提交

🔖 chore(release): release version v{x.y.z} [skip ci]

创建带注释的标签 —
```
v{x.y.z}
```
创建GitHub Release
触发sync-main-to-canary任务 — 将main分支的变更同步回canary分支

Claude Action Guide

Claude操作指南

When the user requests a release:

当用户请求发布时：

Minor Release

Read
```
package.json
```
to get the current version and compute the next minor version
Create a
```
release/v{version}
```
branch from canary
Push and create a PR — title must be
🚀 release: v{version}
Inform the user that merging the PR will automatically trigger the release

读取
```
package.json
```
获取当前版本，计算下一个次要版本
从canary分支创建
```
release/v{version}
```
分支
推送分支并创建PR — 标题必须为
🚀 release: v{version}
告知用户：合并该PR后会自动触发发布流程

Patch Release

Choose the appropriate workflow based on the scenario (see

reference/patch-release-scenarios.md

Weekly Release: Create a
```
release/weekly-{YYYYMMDD}
```
branch from canary, scan
```
git log main..canary
```
to write the changelog, title like
```
🚀 release: 20260222
```
Bug Hotfix: Create a
```
hotfix/
```
branch from main, use a gitmoji prefix title (e.g.
```
🐛 fix: ...
```
)
New Model Launch: Community PRs trigger automatically via title prefix (
```
feat
```
/
```
style
```
), no extra steps needed
DB Migration: Create a
```
release/db-migration-{name}
```
branch from canary, write a dedicated migration changelog

根据场景选择对应的工作流（参考

reference/patch-release-scenarios.md

）：

每周发布：从canary分支创建
```
release/weekly-{YYYYMMDD}
```
分支，通过
```
git log main..canary
```
生成变更日志，标题格式如
```
🚀 release: 20260222
```
漏洞热修复：从main分支创建
```
hotfix/
```
前缀的分支，标题使用gitmoji前缀（如
```
🐛 fix: ...
```
）
新模型上线：社区PR会通过标题前缀（
```
feat
```
/
```
style
```
）自动触发发布，无需额外操作
数据库迁移：从canary分支创建
```
release/db-migration-{name}
```
分支，编写专用的迁移变更日志

Important Notes

重要注意事项

Do NOT manually modify the version in package.json — CI will auto-bump it
Do NOT manually create tags — CI will create them automatically
The Minor Release PR title format is a hard requirement — incorrect format will not use the specified version number
Patch PRs do not need a version number — CI auto-bumps patch +1
All release PRs must include a user-facing changelog

请勿手动修改package.json中的版本号 — CI会自动完成版本更新
请勿手动创建标签 — CI会自动生成标签
Minor Release的PR标题格式为硬性要求 — 格式错误将无法使用指定的版本号
Patch Release的PR无需包含版本号 — CI会自动将补丁号+1
所有发布PR必须包含面向用户的变更日志

Changelog Writing Guidelines

变更日志编写规范

All release PR bodies (both Minor and Patch) must include a user-facing changelog. Scan changes via

git log main..canary --oneline

git diff main...canary --stat

, then write following the format below.

所有发布PR的描述部分（Minor和Patch均需）必须包含面向用户的变更日志。可通过

git log main..canary --oneline

或

git diff main...canary --stat

扫描变更内容，然后按照以下格式编写。

Format Reference

格式参考

Weekly Release: See

reference/changelog-example/weekly-release.md

DB Migration: See

reference/changelog-example/db-migration.md

每周发布：参考

reference/changelog-example/weekly-release.md

数据库迁移：参考

reference/changelog-example/db-migration.md

Writing Tips

编写技巧

User-facing: Describe changes that users can perceive, not internal implementation details
Clear categories: Group by features, models/providers, desktop, stability/fixes, etc.
Highlight key items: Use
```
**bold**
```
for important feature names
Credit contributors: Collect all committers via
```
git log
```
and list alphabetically
Flexible categories: Choose categories based on actual changes — no need to force-fit all categories

面向用户：描述用户可感知的变更，而非内部实现细节
分类清晰：按功能、模型/服务商、桌面端、稳定性/修复等维度分组
突出重点：使用
```
**加粗**
```
标注重要功能名称
感谢贡献者：通过
```
git log
```
收集所有提交者，按字母顺序列出
灵活分类：根据实际变更选择分类，无需强行套用所有类别