docs: add branch protection, commit convention, and gitflow guides

2026-04-16 17:24:14 +08:00 · 2026-04-16 17:24:14 +08:00 · 756af4fb73
commit 756af4fb73
parent 51e4531e95
5 changed files with 478 additions and 0 deletions
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@ -0,0 +1,43 @@
+## Description
+
+<!-- What does this PR do? What problem does it solve? -->
+
+## Type of Change
+
+- [ ] **feat** — New feature
+- [ ] **fix** — Bug fix
+- [ ] **docs** — Documentation changes only
+- [ ] **refactor** — Code refactoring (no functional change)
+- [ ] **perf** — Performance improvement
+- [ ] **test** — Adding or updating tests
+- [ ] **chore** — Build process, auxiliary tools, or CI/CD
+
+## Related Issue
+
+<!-- Link to the related issue, e.g., "Closes #123", "Fixes #456" -->
+
+## Testing
+
+<!-- How has this been tested? What cases does it cover? -->
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Manual testing performed
+
+## Screenshots (if applicable)
+
+<!-- For UI changes, include before/after screenshots -->
+
+## Checklist
+
+- [ ] Code follows the project's coding conventions
+- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] Documentation updated (if needed)
+- [ ] No new warnings or errors
+- [ ] Breaking changes clearly documented
+
+## Additional Notes
+
+<!-- Any other context reviewers should know about -->
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@ -0,0 +1,96 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust-check:
+    name: Rust Lint & Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: apps/* libs/*
+
+      - name: Check formatting
+        run: cargo fmt --workspace -- --check
+
+      - name: Run clippy
+        run: cargo clippy --workspace -- -D warnings
+
+  rust-test:
+    name: Rust Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust
+        uses: dtolnay/rust@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: apps/* libs/*
+
+      - name: Run tests
+        run: cargo test --workspace
+
+  frontend-check:
+    name: Frontend Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: ESLint
+        run: pnpm lint
+
+      - name: Type check
+        run: pnpm tsc --noEmit
+
+  frontend-build:
+    name: Frontend Build
+    runs-on: ubuntu-latest
+    needs: frontend-check
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Upload dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
--- a/docs/BRANCH-PROTECTION.md
+++ b/docs/BRANCH-PROTECTION.md
@ -0,0 +1,71 @@
+# 分支保护规则配置
+
+以下规则需要在 GitHub 仓库设置界面手动配置，或通过 Terraform/Ansible 等基础设施即代码工具自动化。
+
+## main 分支保护规则
+
+路径：**Settings → Branches → Branch protection rules → Add rule**
+
+### 必填项
+
+| 配置项 | 值 | 说明 |
+|--------|-----|------|
+| Branch name pattern | `main` | 匹配 main 分支 |
+| Protect matching branches | ✅ 启用 | 开启分支保护 |
+| **Require pull request reviews** | ✅ 要求 | 合并前至少 1 人 review |
+| **Require approvals** | `1` | 最少审批数量 |
+| Dismiss stale approvals | ✅ 启用 | PR 更新后需重新审批 |
+| Require review from Code Owners | ☐ 可选 | 建议开启 |
+| **Require status checks to pass before merging** | ✅ 要求 | 必须通过 CI |
+| Required status checks | `rust-check`, `rust-test`, `frontend-check` | CI job 名称 |
+| **Require branches to be up to date before merging** | ☐ 可选 | 建议不启用，避免复杂 |
+| Do not allow bypassing the above settings | ✅ 启用 | 即使 admin 不能绕过 |
+
+### 安全设置
+
+| 配置项 | 值 |
+|--------|-----|
+| Lock branch | ☐ 可选（不勾选，CI 仍可推送） |
+| Allow force pushes | ☐ 禁用（禁止 force push） |
+| Allow deletions | ☐ 禁用（禁止删除分支） |
+
+## develop 分支保护规则
+
+路径：**Settings → Branches → Branch protection rules → Add rule**
+
+| 配置项 | 值 |
+|--------|-----|
+| Branch name pattern | `develop` |
+| Protect matching branches | ✅ 启用 |
+| Require pull request reviews | ✅ 要求 |
+| Require approvals | `1` |
+| Dismiss stale approvals | ✅ 启用 |
+| Require status checks to pass before merging | ✅ 要求 |
+| Required status checks | `rust-check`, `rust-test`, `frontend-check` |
+| Do not allow bypassing | ✅ 启用 |
+| Allow force pushes | ☐ 禁用 |
+
+## 自动清理已合并分支
+
+建议安装 GitHub App [Branch Clean Up](https://github.com/apps/branch-cleanup) 或在 PR 合并后自动删除源分支：
+
+- **Settings → General → Automatically delete head branches** → ✅ 启用
+
+## 使用 GitHub CLI 配置（自动化）
+
+如果需要通过代码自动化配置，可以使用 `gh` CLI：
+
+```bash
+# 安装 gh
+brew install gh
+
+# 登录
+gh auth login
+
+# 创建 branch protection rule for main
+gh api repos/{owner}/{repo}/branches/main/protection -X PUT \
+  -f required_status_checks='{"strict":true,"contexts":["rust-check","rust-test","frontend-check"]}' \
+  -f enforce_admins=true \
+  -f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \
+  -f allow_force_pushes=false
+```
--- a/docs/COMMIT-CONVENTION.md
+++ b/docs/COMMIT-CONVENTION.md
@ -0,0 +1,77 @@
+# Commit Message 规范
+
+本项目采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
+
+## 格式
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+## 示例
+
+```
+feat(api): add workspace member invitation endpoint
+fix(frontend): correct sidebar collapse state on resize
+docs: update API documentation for /repos endpoints
+refactor(service): extract auth logic into separate module
+hotfix(k8s): add missing health probe for gitserver
+```
+
+## Type
+
+| Type | Description |
+|------|-------------|
+| `feat` | 新功能 |
+| `fix` | Bug 修复 |
+| `docs` | 仅文档变更 |
+| `style` | 代码格式（不影响功能） |
+| `refactor` | 重构（不是修复也不是新功能） |
+| `perf` | 性能优化 |
+| `test` | 添加或修正测试 |
+| `chore` | 构建或辅助工具变更 |
+| `build` | 影响构建系统或依赖 |
+| `ci` | CI/CD 配置 |
+| `revert` | 回滚之前的提交 |
+
+## Scope
+
+| Scope | 说明 |
+|-------|------|
+| `frontend` | React 前端 |
+| `api` | REST API 路由 |
+| `service` | 业务逻辑层 |
+| `models` | 数据库模型 |
+| `k8s` | Kubernetes 部署 |
+| `deploy` | Docker/Helm 部署 |
+| `git` | Git 仓库功能 |
+| `room` | 实时聊天 |
+| `agent` | AI Agent |
+| `db` | 数据库迁移 |
+
+## 规则
+
+1. **每条提交应仅包含一个逻辑变更**
+2. **description 首字母小写，使用祈使句**
+3. **禁止句号结尾**
+4. **Body 解释 what 和 why，不解释 how**
+5. **Footer 引用相关 Issue**
+
+## Git Alias
+
+在 `~/.gitconfig` 中添加快捷别名：
+
+```ini
+[alias]
+  co = checkout
+  cm = commit -m
+  lg = log --oneline --graph --decorate
+  amend = commit --amend --no-edit
+  uncommit = reset --soft HEAD~1
+```
+
+或使用 commitlint 钩子自动验证（见 `.husky/commit-msg`）。
--- a/docs/GITFLOW.md
+++ b/docs/GITFLOW.md
@ -0,0 +1,191 @@
+# 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
+```