gitdataai/docs/GITFLOW.md

Git Flow 分支策略

概述

本项目采用 Git Flow 分支模型，结合 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)

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

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

2. 发布准备 (release)

# 从 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)

# 从 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 格式：

<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) 策略

使用语义化版本号：

# 发布标签
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 修复

分支清理

功能分支合并后应删除：

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

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