toRolex Git Flow 分支管理与提交规范
基于 Vincent Driessen 的 A Successful Git Branching Model，指导团队按 GitFlow 进行分支操作、提交和合并。
完整分支模型、命名规范、红线、对比矩阵见 references/gitflow.md。
操作命令速查
Develop 分支初始化
git branch develop
git push -u origin develop
Feature 分支
开始开发：
git checkout -b feature/<功能名> develop
git push -u origin feature/<功能名>
提交代码：
git add .
git commit -m "feat(<模块>): <简述>"
合并回 develop（使用 --no-ff 保留分支 commit 历史）：
git checkout develop
git pull origin develop
git merge --no-ff feature/<功能名>
git push origin develop
清理：
git branch -d feature/<功能名>
git push origin --delete feature/<功能名>
Release 分支
开始发版：
git checkout -b release/<版本号> develop
完成发版：
# 合并到 master
git checkout master
git merge --no-ff release/<版本号>
git push origin master
# 合并回 develop
git checkout develop
git merge --no-ff release/<版本号>
git push origin develop
# 打 tag + 清理
git tag -a v<版本号> -m "Release v<版本号>"
git push --tags
git branch -d release/<版本号>
git push origin --delete release/<版本号>
Hotfix 分支
开始修复：
git checkout -b hotfix/<版本号> master
完成修复：
# 合并到 master
git checkout master
git merge --no-ff hotfix/<版本号>
git push origin master
# 合并回 develop
git checkout develop
git merge --no-ff hotfix/<版本号>
git push origin develop
# 打 tag + 清理
git tag -a v<版本号> -m "Hotfix v<版本号>"
git push --tags
git branch -d hotfix/<版本号>
git push origin --delete hotfix/<版本号>
合并策略
| 策略 | 说明 | 适用场景 |
|---|---|---|
--no-ff |
不使用 fast-forward，保留分支 commit 历史 | 默认推荐，保留完整开发记录 |
--squash |
把多次分支 commit 压缩为一次 | 功能分支 commit 杂乱时 |
Commit Message 规范
采用 Conventional Commits 格式：
<type>(<scope>): <subject>
[optional body]
[optional footer]
Type 类型
| Type | 说明 | 示例 |
|---|---|---|
feat |
新功能 | feat(auth): add JWT token refresh |
fix |
Bug 修复 | fix(api): handle null user profile |
docs |
文档变更 | docs(readme): update install guide |
style |
格式调整（不影响逻辑） | style(layout): reorder imports |
refactor |
重构 | refactor(db): extract query builder |
perf |
性能优化 | perf(list): add virtual scrolling |
test |
测试相关 | test(auth): add 2FA unit tests |
chore |
构建/工具变更 | chore(deps): bump axios to 1.6 |
ci |
CI 配置 | ci: add GitHub Actions workflow |
revert |
回滚 | revert: undo feat(user-search) |
规则
- Subject 用现在时、首字母小写、不加句号
- 中文项目 scope 可用中文，如
feat(登录): 增加验证码校验 - Body 解释 为什么 这个变更是必要的
- Footer 引用关联 issue：
Closes #123
PR / MR 规范
分支准备
提交 PR 前必须：
- 从目标分支 rebase 或 merge 最新代码
- 确保 CI 通过
- 自己 Review 一遍 diff
# Rebase 到最新 develop
git fetch origin
git rebase origin/develop
# 解决冲突后
git push --force-with-lease origin feature/<功能名>
PR 描述模板
## 变更说明
<一句话描述做了什么>
## 变更类型
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 重构 (refactor)
- [ ] 其他
## 测试
- [ ] 单元测试通过
- [ ] 手动验证通过
## 关联 Issue
Closes #<编号>
合并策略选择
| 策略 | 适用场景 |
|---|---|
--no-ff (non-fast-forward) |
默认推荐。保留分支历史，可追溯功能开发过程 |
--squash |
功能分支 commit 杂乱时，压缩成一个干净 commit |
--ff-only |
简单修复，分支历史已是线性时 |
Release Note 格式
每次发版必须使用规范的 Release Note 格式，通过 gh release create 或 gh release edit 发布。
格式参考：见 references/release-note-format.md
快速要点：
- 固定分类：新功能 / 问题修复 / 文档 / 测试 / 杂项
- 无变更时写"无"，不可省略
- 摘要 2-4 句概括核心变更
- 升级指南给出具体命令
- 尾部带
compare链接
创建命令：
gh release create v<版本号> --title "v<版本号>: <简述>" --notes "<完整 note>" --target main
扩展：其他主流工作流
完整 Git Flow 偏重，主干又必须稳定时，还有两种常见替代：GitHub Flow（轻量 + PR 强协作）和 Trunk-Based Development（主干高频集成）。
各工作流完整内容：
- GitFlow（含横向对比矩阵 + 选型决策表）：
references/gitflow.md - GitHub Flow：
references/github-flow.md - Trunk-Based Development：
references/trunk-based.md
何时读这些 reference：
- 用户明确问"我们应不应该换工作流"——先读
references/gitflow.md顶部拿对比矩阵和决策表 - 用户已经在用 GitHub Flow / Trunk-Based——直接读对应文件
- 用户在 GitFlow 上下文里讨论某条特定规则——留在主文件即可，不要跳转