Git分支管理规范

Trunk Based / Git Flow 选型与分支策略

分支模型选型

选型原则

Requirement：团队规模 ≤ 10 人、迭代周期 ≤ 2 周、追求快速交付的项目，默认采用 Trunk Based Development（TBD）。
Standard：团队规模 > 10 人、存在多版本并行维护、需要严格发布节奏的项目，可采用 Git Flow。
Caution：禁止同一仓库内混用两种分支模型；选型一旦确定，需在仓库 README.md 与 CONTRIBUTING.md 中声明。

TBD 模型要点

仅存在一个长期分支 main（即主干），所有开发通过短期特性分支合入主干。
特性分支生命周期 ≤ 1 天，合入后立即删除。
通过 Feature Flag 控制未完成功能的可见性，而非长期保留分支。
主干必须保持可发布状态（Green Build）。

Git Flow 模型要点

分支类型	命名	生命周期	来源	合入目标
主干	`main`	永久	—	—
开发	`develop`	永久	`main`	`main`（发布时）
特性	`feature/*`	临时	`develop`	`develop`
发布	`release/*`	临时	`develop`	`main` + `develop`
热修	`hotfix/*`	临时	`main`	`main` + `develop`
支撑	`support/*`	长期（旧版本维护）	对应版本 tag	自身

反模式：在 TBD 项目中保留 develop 分支；特性分支存活超过 3 天；main 长期处于不可构建状态。

分支命名

命名规则

Requirement：分支名必须小写，使用连字符 - 分隔单词，禁止使用下划线 _ 或驼峰。
Requirement：分支名必须以类型前缀开头，格式：<type>/<short-description>。
Standard：描述部分建议包含任务编号（如 Jira / GitHub Issue ID），便于追溯。

类型前缀

前缀	用途	示例
`feature/`	新功能开发	`feature/user-login`
`bugfix/`	缺陷修复（非生产紧急）	`bugfix/fix-null-pointer`
`hotfix/`	生产环境紧急修复	`hotfix/payment-timeout`
`release/`	发布准备	`release/v1.2.0`
`chore/`	工程杂项（配置、脚本）	`chore/update-ci-config`
`docs/`	文档变更	`docs/update-readme`
`refactor/`	重构（不改变外部行为）	`refactor/extract-service`
`perf/`	性能优化	`perf/reduce-db-query`
`test/`	测试相关	`test/add-user-api-cases`

任务编号嵌入

Standard：若使用任务追踪系统，建议在描述中嵌入编号：

feature/JIRA-123-user-login
bugfix/ISSUE-456-fix-pagination

反模式：

my-branch、test123、fix —— 无类型前缀、无意义。
Feature/UserLogin —— 大小写混合。
feature_user_login —— 使用下划线。
feature/add-user-login-functionality-to-the-system —— 过长（建议 ≤ 50 字符）。

合并策略

合并方式

Requirement：合入 main / develop 必须通过 Pull Request（PR）/ Merge Request（MR），禁止直接 push。
Standard：默认合并方式为 Squash Merge（压缩合并），保持主干提交历史简洁。
Suggestion：对于长期分支（如 release/* → main），可使用 Merge Commit 保留分支脉络。
Caution：禁止使用 git push --force 到受保护分支（main、develop、release/*）。

Squash Merge 提交信息

Standard：Squash 后的提交信息需符合 Git提交规范，类型由 PR 中包含的提交决定，优先取最高影响级别：

feat: add user login with OAuth2 support (#123)

Rebase 使用

Standard：在特性分支上，使用 git rebase main 同步主干更新，避免产生无意义的 merge commit。
Caution：rebase 会改写历史，仅在自己的特性分支上执行，且分支未被他人共享时使用。

冲突处理

Requirement：合并冲突必须由分支作者本人解决，禁止由他人代解决后直接合入。
Standard：解决冲突后，必须重新运行本地测试与 lint，确认无误后再推送。

分支保护

受保护分支

Requirement：main、develop、release/* 必须设置为受保护分支，禁止直接 push。
Requirement：受保护分支必须开启 强制推送拒绝（Reject Force Push）。
Standard：受保护分支必须开启 删除保护（Prevent Branch Deletion）。

合并准入条件

Requirement：PR 合入前必须通过 CI 流水线（lint + 单元测试 + 构建）。
Requirement：PR 必须获得至少 1 名 Code Reviewer 的 Approve（核心仓库 ≥ 2 人）。
Standard：PR 必须通过静态安全扫描（如 Snyk、Semgrep）。
Standard：PR 合入前必须与目标分支无冲突（up-to-date）。

PR 模板

Standard：仓库根目录必须提供 .github/PULL_REQUEST_TEMPLATE.md，包含以下字段：

## 变更类型
- [ ] feature 新功能
- [ ] bugfix 缺陷修复
- [ ] refactor 重构
- [ ] docs 文档
- [ ] chore 工程杂项
 
## 变更说明
<!-- 简要描述本次变更的目的与内容 -->
 
## 关联任务
<!-- JIRA-xxx / #issue -->
 
## 测试情况
- [ ] 单元测试通过
- [ ] 已添加/更新测试用例
- [ ] 本地手动验证
 
## 自检清单
- [ ] 代码符合团队编码规范
- [ ] 无敏感信息（密钥、token）泄露
- [ ] 已更新相关文档

常用操作

创建特性分支（TBD）

# 从最新主干创建
git checkout main
git pull origin main
git checkout -b feature/user-login
 
# 开发并提交
git add .
git commit -m "feat: add user login page"
 
# 推送并创建 PR
git push origin feature/user-login
gh pr create --fill

同步主干更新

# 方式一：rebase（推荐，保持线性历史）
git checkout feature/user-login
git fetch origin
git rebase origin/main
 
# 方式二：merge（适合多人共享的分支）
git merge origin/main

合入后清理

Standard：PR 合入后，源分支应自动删除（在 Git 平台设置中开启），本地分支手动清理：

git checkout main
git pull origin main
git branch -d feature/user-login
git remote prune origin

紧急热修（Git Flow）

# 从 main 创建 hotfix 分支
git checkout main
git pull origin main
git checkout -b hotfix/payment-timeout
 
# 修复并提交
git commit -m "fix: resolve payment gateway timeout"
 
# 合入 main 与 develop
git checkout main
git merge --no-ff hotfix/payment-timeout
git tag -a v1.2.1 -m "hotfix: payment timeout"
 
git checkout develop
git merge --no-ff hotfix/payment-timeout
 
git branch -d hotfix/payment-timeout

反模式

❌ 直接在 main 上提交并 push。
❌ 一个 PR 包含多个不相关的功能变更（应拆分）。
❌ 长期不合并的特性分支（> 3 天），导致合并冲突累积。
❌ 使用 git reset --hard 丢弃他人提交。
❌ 在公共分支上执行 git push --force。