192 lines
4.4 KiB
Markdown
192 lines
4.4 KiB
Markdown
# 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
|
||
```
|