Branch Strategy

🌿 分支策略

Monolith 采用 dev → PR → squash merge → main 单线工作流。

---

分支模型

main      ───●─────●─────────●───────●────────►   (生产唯一)
              ▲     ▲         ▲       ▲
              │     │         │       │
              squash merge (历史扁平)
              │     │         │       │
dev       ────●──●──●─●─●──●──●──●─●──●─────►    (日常开发)

分支	用途	保护
main	生产分支，触发自动部署	✅ 禁止直推、必须 PR、必须 squash
dev	日常开发汇总	推荐由各 feature 分支汇入
feature/*	单个功能 / 修复分支	完成后向 dev 或直接 main 开 PR

---

标准开发流程

# 1. 同步最新 dev
git checkout dev
git pull origin dev

# 2. 开发
# (修改代码，运行 npm run lint)

# 3. 提交（Conventional Commits）
git add .
git commit -m "feat(client): 新增标签云组件"

# 4. 推送
git push origin dev

# 5. 在 GitHub 开 PR: dev → main
gh pr create --base main --head dev \
  --title "feat: 标签云组件" \
  --body "## 变更\n- ..."

# 6. 等待 CI / 主人审核

# 7. 主人合并（squash）

# 8. 本地清理
git checkout main && git pull

⚠️ 铁律: 禁止 git push origin main。pr-flow-guard skill 会拦截。

---

Conventional Commits

提交信息格式：

<type>(<scope>): <subject>

Type 类型

Type	用途	触发版本
feat	新功能	minor
fix	Bug 修复	patch
perf	性能优化	patch
refactor	重构（无功能变化）	patch
docs	文档	-
style	格式（空格、分号等）	-
test	测试	-
build	构建系统 / 依赖	-
ci	CI 配置	-
chore	杂项	-

Scope 推荐

client, server, db, storage, deploy, ci, docs, security, wiki

示例

feat(client): 评论楼层支持 Markdown
fix(server): 修复 JWT 过期边界 bug
perf(db): 文章列表查询走索引
docs(wiki): 重构 API 参考
chore(deps): 升级 Hono 到 4.6

---

Squash Merge 规则

• 唯一允许的合并方式
• PR 标题作为最终 commit message（务必符合 Conventional Commits）
• 合并后删除源分支保持仓库整洁
• 历史线性，方便 git log --oneline 浏览

---

版本号管理

遵循 SemVer 2.0：

MAJOR.MINOR.PATCH
  │     │     └── 向后兼容的 bug 修复
  │     └──────── 向后兼容的功能新增
  └────────────── 不兼容的 API 变更

升级时机

• 每次 PR 合并到 main 后 升 PATCH/MINOR
• 重大架构变更 升 MAJOR

操作

# 在 main 分支
npm version patch -m "chore(release): v%s"
git push origin main --tags

# 创建 GitHub Release
gh release create v0.2.1 --generate-notes

或通过 GitHub Web Releases 页面创建 tag + release notes。

---

分支保护配置

Settings → Branches → main:

• ✅ Require a pull request before merging
• ✅ Require approvals: 1 (主人)
• ✅ Require status checks: lint, deploy-cloudflare (可选)
• ✅ Require linear history
• ✅ Restrict who can push to matching branches: 仅 admins
• ✅ Allow squash merging only (禁用 merge commit / rebase)

---

紧急修复流程

生产 bug 紧急修复：

git checkout -b hotfix/critical-bug main
# 修复
git commit -m "fix(server): 紧急修复 token 续签崩溃"
git push origin hotfix/critical-bug

# 直接对 main 开 PR
gh pr create --base main --head hotfix/critical-bug --title "fix: 紧急 token bug"

# 主人立即审核合并
# 合并后立即 cherry-pick 到 dev 保持同步
git checkout dev
git cherry-pick <commit-sha>

---

延伸阅读

• 部署指南 — main 合并后的自动部署链
• 安全设计 — CI 阻塞合并的检查项
• Conventional Commits 官方