77 lines
3.1 KiB
Markdown
77 lines
3.1 KiB
Markdown
# Git 分支策略（简化版 GitFlow）
|
||
|
||
本文档是项目分支流的**唯一事实源**。决策背景与理由见 [decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)。
|
||
|
||
## 分支角色
|
||
|
||
| 分支 | 从哪拉 | merge 回 | 用途 |
|
||
|------|--------|----------|------|
|
||
| `main` | — | — | 可发布稳定版；只经 `dev`（或 `hotfix`）进入，不直接收 feature |
|
||
| `dev` | `main` | — | 集成点；所有 feature 先合到这里 |
|
||
| `feature/<name>` | `dev` | `dev` | 单一功能/模块开发，完成后合回 dev |
|
||
| `hotfix/<name>` | `main` | `main` + `dev` | 线上紧急修复（按需，当前阶段少用） |
|
||
|
||
> 当前不引入 `release/*`：基础建设阶段收益低。进入正式发布周期后再升级（见 ADR-0005「后果」）。
|
||
|
||
## 完整流程
|
||
|
||
```text
|
||
main ───────────────────────────────● 稳定/可发布（只经 dev 或 hotfix 进入）
|
||
▲ merge（需你确认）
|
||
dev ──●────●────●───────────────────┘ 集成点（接收所有 feature）
|
||
│ │ │
|
||
feature/ feature/ feature/ 从 dev 拉，merge 回 dev
|
||
auth checkin plan
|
||
```
|
||
|
||
## 命名约定
|
||
|
||
- `feature/<name>` 的 `<name>` 与 `feature/<name>/` 模块目录名一致（如 `feature/auth`）；非模块功能用 kebab-case 短名（如 `feature/onboarding-flow`）。
|
||
- `<name>` 一律 kebab-case：小写、短横线分隔，不混用下划线。
|
||
|
||
## 各分支规则
|
||
|
||
- **feature**：从 dev 拉 → 开发 → 跑 `bash scripts/verify.sh` → merge 回 dev。一次 feature 一个主题。
|
||
- **dev**：集成点，保持可构建；合入前必须通过完整验证。
|
||
- **main**：只放可发布状态；进入 main 必须经人工确认。
|
||
|
||
## 自动化边界
|
||
|
||
| 动作 | Claude 行为 |
|
||
|------|-------------|
|
||
| 从 dev 拉 `feature/<name>` | ✅ 自动 |
|
||
| 按 `type(scope): description` 提交 | ✅ 自动 |
|
||
| 跑 `scripts/verify.sh` 作为「完成」证据 | ✅ 自动 |
|
||
| merge 回 `dev` | ⚠️ 默认先给 diff，确认后合 |
|
||
| merge 到 `main` | ❌ 永远先问你，绝不自动 |
|
||
| rebase / force-push | ❌ 需显式确认 |
|
||
| 删除远程分支 | ⚠️ 确认后执行 |
|
||
|
||
## 操作清单
|
||
|
||
```bash
|
||
# 开始一个 feature（以 auth 为例）
|
||
git checkout dev && git pull
|
||
git checkout -b feature/auth
|
||
|
||
# ...开发、按 type(scope): description 提交...
|
||
|
||
# 完成后合并回 dev
|
||
bash scripts/verify.sh # 必须先通过
|
||
git checkout dev && git pull
|
||
git merge --no-ff feature/auth # --no-ff 保留 feature 边界，便于追溯
|
||
git push origin dev
|
||
|
||
# dev 稳定后合入 main（需你确认）
|
||
git checkout main && git pull
|
||
git merge --no-ff dev
|
||
git push origin main
|
||
# 发布时按需打 tag：git tag -a v0.x.y -m "..." && git push origin --tags
|
||
```
|
||
|
||
## 关联
|
||
|
||
- 决策记录：[decisions/0005-branching-strategy.md](decisions/0005-branching-strategy.md)
|
||
- 提交格式：[conventions.md](conventions.md)
|
||
- 构建与发布：[deployment.md](deployment.md)
|