# Git Flow 分支策略

## 概述

本项目采用 [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) 分支模型，结合 GitHub Flow 的简洁性，适合本项目的发布节奏。

## 分支结构

```
main                    ← 生产环境，始终保持可发布状态
│
├── develop             ← 开发集成分支，所有功能分支合并至此
│   │
│   ├── feature/xxx     ← 功能分支，从 develop 创建
│   │
│   ├── release/0.3.0   ← 发布分支，从 develop 创建
│   │
│   └── hotfix/0.2.10   ← 热修复分支，从 main 创建
```

## 长期分支

| 分支 | 用途 | 保护状态 |
|------|------|----------|
| `main` | 生产环境代码 | 强制保护，禁止 force push |
| `develop` | 开发集成，所有功能最终汇入 | 建议保护 |

## 临时分支

| 前缀 | 用途 | 创建来源 | 合并目标 |
|------|------|----------|----------|
| `feature/` | 新功能开发 | `develop` | `develop` |
| `release/` | 发布准备 | `develop` | `main` + `develop` |
| `hotfix/` | 生产环境紧急修复 | `main` | `main` + `develop` |

## 工作流程

### 1. 功能开发 (feature)

```bash
# 从 develop 创建功能分支
git checkout develop
git checkout -b feature/user-dashboard

# 开发完成后，提交 PR 到 develop
git push origin feature/user-dashboard
```

### 2. 发布准备 (release)

```bash
# 从 develop 创建发布分支
git checkout develop
git checkout -b release/0.3.0

# 在 release 分支上做最后的修复和版本号更新
# 修复完成后，合并到 main 并打标签
git checkout main
git merge release/0.3.0 --no-ff
git tag -a v0.3.0 -m "Release v0.3.0"

# 同时合并回 develop
git checkout develop
git merge release/0.3.0 --no-ff

# 删除发布分支
git branch -d release/0.3.0
```

### 3. 热修复 (hotfix)

```bash
# 从 main 创建热修复分支
git checkout main
git checkout -b hotfix/0.2.10

# 修复完成后，合并到 main 并打标签
git checkout main
git merge hotfix/0.2.10 --no-ff
git tag -a v0.2.10 -m "Hotfix v0.2.10"

# 同时合并回 develop
git checkout develop
git merge hotfix/0.2.10 --no-ff

# 删除热修复分支
git branch -d hotfix/0.2.10
```

## 分支命名规范

```
feature/<issue-id>-<简短描述>
release/<版本号>
hotfix/<版本号>
```

示例：
- `feature/123-user-dashboard`
- `feature/456-oauth-integration`
- `release/0.3.0`
- `hotfix/0.2.10`

## 合并 (Merge) 策略

- **功能分支 → develop**：使用 `git merge --no-ff`，保留功能分支历史
- **release → main + develop**：使用 `git merge --no-ff`
- **hotfix → main + develop**：使用 `git merge --no-ff`
- **PR 合并**：在 GitHub 界面使用 "Squash and merge" 或 "Create a merge commit"

## 提交信息规范

采用 [Conventional Commits](https://www.conventionalcommits.org/) 格式：

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

### Type 类型

| Type | 说明 |
|------|------|
| `feat` | 新功能 |
| `fix` | Bug 修复 |
| `docs` | 仅文档变更 |
| `style` | 代码格式（不影响功能） |
| `refactor` | 重构（不是修复也不是新功能） |
| `perf` | 性能优化 |
| `test` | 添加或修正测试 |
| `chore` | 构建或辅助工具变更 |

### Scope 范围

使用受影响的主要模块：

| Scope | 说明 |
|-------|------|
| `frontend` | 前端代码 |
| `backend` | 后端通用 |
| `api` | API 路由/Handler |
| `service` | 业务逻辑层 |
| `models` | 数据库模型 |
| `k8s` | Kubernetes 部署 |
| `deploy` | 部署配置 |
| `git` | Git 相关功能 |
| `room` | 实时聊天功能 |
| `agent` | AI Agent 功能 |
| `db` | 数据库/迁移 |

### 示例

```
feat(frontend): add user dashboard page
fix(api): handle nil pointer in workspace handler
docs: update API documentation for /repos endpoints
refactor(service): extract auth logic into separate module
hotfix(k8s): add missing health probe for gitserver
```

## 标签 (Tag) 策略

使用语义化版本号：

```bash
# 发布标签
git tag -a v0.2.9 -m "Release v0.2.9"

# 带签名的标签（推荐）
git tag -s v0.2.9 -m "Release v0.2.9"
```

版本号格式：`v<major>.<minor>.<patch>`
- `major`：破坏性变更
- `minor`：新功能（向后兼容）
- `patch`：Bug 修复

## 分支清理

功能分支合并后应删除：

```bash
# 删除本地分支
git branch -d feature/xxx

# 删除远程分支
git push origin --delete feature/xxx
```