Git flow conventions

Git Flow 分支管理与提交规范

基于 Vincent Driessen 的 A Successful Git Branching Model， 指导团队按照标准化流程进行分支操作、提交和代码合并。

核心分支模型

master (production)    ●───●─────────●────────── ● ──●
                        \   /           \         /   /
release                  ●─●    v1.0     ●───●   /   /
                          \              /     \ /   /
develop  ●────●────●──────●────●───●────●───────●───●────
           \    \    \      /      \    \     /
feature     ●─┐  ●─┐  ●───●        ●─┐  ●───●
              │    │                  │    │
hotfix        │    │                  │    ●────────────●
              │    │                  │

分支类型与命名规范

分支类型	命名格式	来源	合并目标	说明
master	master / main	—	—	生产环境代码，只接受合并
develop	develop	master	—	主开发分支
feature	feature/<功能简述>	develop	develop	新功能开发
release	release/<版本号>	develop	master + develop	发布准备
hotfix	hotfix/<版本号>	master	master + develop	线上紧急修复

命名示例

• feature/user-auth — 用户认证功能
• feature/add-dashboard — 新增仪表盘
• release/1.2.0 — 1.2.0 版本发布
• hotfix/1.1.1 — 修复 1.1.0 线上问题

原则：全小写，英文单词用连字符分隔，简洁描述目的。

操作命令速查

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 前必须：

1. 从目标分支 rebase 或 merge 最新代码
2. 确保 CI 通过
3. 自己 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

关键红线

• 禁止 直接在 master/main 上修改代码
• 禁止 直接在 develop 上开发功能，必须走 feature 分支
• 禁止 在 Release 分支打好后从 develop 合入新功能
• 必须 使用 --no-ff 合并 feature/release/hotfix 到主分支
• 必须 每次 Release/Hotfix 后在 master 上打 tag
• 必须 删除已合并的 feature/release/hotfix 远程分支

简化版工作流（小型团队）

如果完整 Git Flow 太重，可简化为：

main ●────────────●─────●
       \          /     /
feature ●──●──●──●     /
         \             /
bugfix   ●───────────●

• main — 生产分支
• feature/<名称> — 功能分支，合入 main
• bugfix/<名称> — 修复分支，合入 main

不区分 release/hotfix，直接在 main 上打 tag 发版。