android-client/docs/gitflow.md

Git 分支策略（简化版 GitFlow）

本文档是项目分支流的唯一事实源。决策背景与理由见 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「后果」）。

完整流程

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	❌ 需显式确认
删除远程分支	⚠️ 确认后执行

操作清单

# 开始一个 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
• 提交格式：conventions.md
• 构建与发布：deployment.md