# 分支管理规范

## 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 创建功能分支

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

### 4.2 合并功能到 dev

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

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

# 推送 dev 分支
git push origin dev
```

### 4.3 创建发布分支

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

### 4.4 发布到 main

```bash
# 在 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 热修复操作

```bash
# 从 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`）的代码将被回退，提交者需要重新按照规范流程提交代码。