From 756af4fb738512bd2f4f860d7d91ca7efa87ef26 Mon Sep 17 00:00:00 2001 From: ZhenYi <434836402@qq.com> Date: Thu, 16 Apr 2026 17:24:14 +0800 Subject: [PATCH] docs: add branch protection, commit convention, and gitflow guides --- .github/pull_request_template.md | 43 +++++++ .github/workflows/ci.yml | 96 ++++++++++++++++ docs/BRANCH-PROTECTION.md | 71 ++++++++++++ docs/COMMIT-CONVENTION.md | 77 +++++++++++++ docs/GITFLOW.md | 191 +++++++++++++++++++++++++++++++ 5 files changed, 478 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/ci.yml create mode 100644 docs/BRANCH-PROTECTION.md create mode 100644 docs/COMMIT-CONVENTION.md create mode 100644 docs/GITFLOW.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..b20bff2 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,43 @@ +## Description + + + +## 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 + + + +## Testing + + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing performed + +## Screenshots (if applicable) + + + +## 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 + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..163095f --- /dev/null +++ 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/ diff --git a/docs/BRANCH-PROTECTION.md b/docs/BRANCH-PROTECTION.md new file mode 100644 index 0000000..114961e --- /dev/null +++ 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 +``` diff --git a/docs/COMMIT-CONVENTION.md b/docs/COMMIT-CONVENTION.md new file mode 100644 index 0000000..44c95e1 --- /dev/null +++ b/docs/COMMIT-CONVENTION.md @@ -0,0 +1,77 @@ +# Commit Message 规范 + +本项目采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。 + +## 格式 + +``` +(): + +[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`）。 diff --git a/docs/GITFLOW.md b/docs/GITFLOW.md new file mode 100644 index 0000000..31a2a00 --- /dev/null +++ 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/-<简短描述> +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/) 格式： + +``` +(): + +[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`：Bug 修复 + +## 分支清理 + +功能分支合并后应删除： + +```bash +# 删除本地分支 +git branch -d feature/xxx + +# 删除远程分支 +git push origin --delete feature/xxx +```