coze-studio/docs/BRANCH_MANAGEMENT.md

分支管理规范

1. 分支类型与命名规范

1.1 分支命名格式

分支类型	命名格式	示例
主分支	main	main
开发分支	dev	dev
功能分支	feat/<功能名>	feat/event, feat/stream
热修复分支	hotfix/<问题名>	hotfix/event
发布分支	release/<版本号>	release/v1.0.0

1.2 分支用途说明

分支类型	用途说明
main	稳定版本分支，直接对应生产环境代码
dev	开发主分支，所有功能集成分支先合并到此分支
feat/*	功能开发分支，用于开发新功能
hotfix/*	热修复分支，用于紧急修复生产问题
release/*	发布分支，用于版本发布准备

---

2. 分支流程规则

2.1 核心规则：dev 禁止合并到 main

重要约束：dev 分支 禁止直接合并到 main 分支

• dev 是开发分支，代码未经充分测试，不适合直接发布到生产
• 所有合并到 main 的代码必须通过 release/* 分支或直接从 hotfix/* 分支合并

2.2 标准合并流程

功能开发流程：
feat/* → dev → release/* → main

热修复流程：
hotfix/* → main (紧急情况可直接合并)
hotfix/* → dev  (同步修复到开发分支)

2.3 各分支合并规则

从分支	合并到	是否允许	说明
feat/*	dev	✅ 允许	功能开发完成后合并到开发分支
dev	main	❌ 禁止	dev 禁止直接合并到 main
dev	release/*	✅ 允许	开发分支可以合并到发布分支
release/*	main	✅ 允许	发布分支通过测试后合并到 main
release/*	dev	✅ 允许	发布分支可同步回开发分支
hotfix/*	main	✅ 允许	热修复可直接合并到 main
hotfix/*	dev	✅ 允许	热修复需同步到开发分支
feat/*	main	❌ 禁止	功能分支禁止直接合并到 main
feat/*	其他 feat/*	❌ 禁止	功能分支之间禁止互相合并

---

3. 当前项目分支结构

本地分支：
  - dev          (开发主分支，当前工作分支)
  - feat/event   (事件功能分支)
  - feat/stream  (流功能分支)
  - hotfix/event (事件热修复分支)
  - main         (生产环境分支)

远程分支：
  - origin/main
  - origin/dev
  - origin/feat/event

---

4. Git 操作指南

4.1 创建功能分支

# 从 main 创建功能分支
git checkout main
git pull origin main
git checkout -b feat/your-feature-name

4.2 合并功能到 dev

# 完成功能开发后，切换到 dev 分支
git checkout dev
git pull origin dev

# 合并功能分支
git merge feat/your-feature-name

# 推送 dev 分支
git push origin dev

4.3 创建发布分支

# 从 dev 创建发布分支
git checkout dev
git pull origin dev
git checkout -b release/v1.0.0

4.4 发布到 main

# 在 release 分支完成测试后，合并到 main
git checkout main
git pull origin main
git merge release/v1.0.0
git push origin main

# 删除发布分支
git branch -d release/v1.0.0
git push origin --delete release/v1.0.0

4.5 热修复操作

# 从 main 创建热修复分支
git checkout main
git pull origin main
git checkout -b hotfix/issue-description

# 修复完成后，合并到 main
git checkout main
git merge hotfix/issue-description
git push origin main

# 同时合并到 dev
git checkout dev
git merge hotfix/issue-description
git push origin dev

# 删除热修复分支
git branch -d hotfix/issue-description

---

5. 注意事项

1. 禁止强制推送：git push --force 可能导致代码丢失，禁止在 main 和 dev 分支使用

2. 保持 dev 稳定：在合并到 dev 之前，确保代码已经过本地测试

3. 及时清理：功能完成后及时删除已合并的 feat/* 分支

4. 提交信息规范：

   • feat: 新功能
   • fix: 修复 bug
   • docs: 文档更新
   • style: 代码格式
   • refactor: 重构
   • chore: 构建/工具变更

5. Pull Request：合并到 main 必须通过 Pull Request 流程，确保代码审查通过

---

6. 违规处理

违反分支合并规则（如将 dev 直接合并到 main）的代码将被回退，提交者需要重新按照规范流程提交代码。