docs: add branch protection, commit convention, and gitflow guides
This commit is contained in:
ZhenYi
parent
51e4531e95
commit
756af4fb73
43
.github/pull_request_template.md
vendored
Normal file
43
.github/pull_request_template.md
vendored
Normal file
@ -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 -->
|
||||||
96
.github/workflows/ci.yml
vendored
Normal file
96
.github/workflows/ci.yml
vendored
Normal file
@ -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/
|
||||||
71
docs/BRANCH-PROTECTION.md
Normal file
71
docs/BRANCH-PROTECTION.md
Normal file
@ -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
|
||||||
|
```
|
||||||
77
docs/COMMIT-CONVENTION.md
Normal file
77
docs/COMMIT-CONVENTION.md
Normal file
@ -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`）。
|
||||||
191
docs/GITFLOW.md
Normal file
191
docs/GITFLOW.md
Normal file
@ -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
|
||||||
|
```
|
||||||
Loading…
Reference in New Issue
Block a user