Appearance
多人协作规范
团队协作规范是高效协作的基础。明确的规范减少沟通成本，提升代码质量。
提交信息规范（Conventional Commits）
见本教程「提交」章节的详细说明。核心规范：
<type>(<scope>): <description>
[optional body]
[optional footer]团队应在 README 或贡献指南中明确规定使用的 type 列表。
分支命名规范
统一的分支命名让团队成员一眼看出分支用途：
功能分支: feature/<ticket-id>-<brief-description>
feature/USER-123-user-avatar-upload
feature/add-search-functionality
修复分支: fix/<ticket-id>-<brief-description>
fix/BUG-456-login-crash-on-ios
热修复分支: hotfix/<version>-<brief-description>
hotfix/1.2.1-null-pointer-exception
发布分支: release/<version>
release/1.3.0
实验分支: experiment/<description>
experiment/graphql-migration
个人工作分支: dev/<username>/<description>
dev/zhangsan/refactor-auth配置分支命名检查（pre-push 钩子）：
bash
#!/bin/sh
# .git/hooks/pre-push
branch=$(git branch --show-current)
valid_branch_regex="^(main|master|develop|HEAD)$|^(feature|fix|hotfix|release|experiment|chore|docs|refactor|test|dev)/[a-z0-9._/-]+"
if ! echo "$branch" | grep -qE "$valid_branch_regex"; then
echo "❌ 分支名 '$branch' 不符合规范！"
echo "请使用格式：feature/xxx, fix/xxx, hotfix/x.x.x-xxx 等"
exit 1
fi
exit 0PR 描述模板
在 .github/pull_request_template.md 或 .gitlab/merge_request_templates/default.md 中创建模板（已在代码审查章节展示）。
多模板支持（GitHub）：
.github/
└── PULL_REQUEST_TEMPLATE/
├── feature.md # 功能 PR 模板
├── bugfix.md # Bug 修复模板
└── hotfix.md # 热修复模板CODEOWNERS 文件
CODEOWNERS 定义了代码的责任人，当这些文件被修改时，对应的负责人会自动被加为 reviewer：
# .github/CODEOWNERS（GitHub）
# .gitlab/CODEOWNERS（GitLab）
# 全局默认 reviewer
* @tech-lead
# 前端代码
/src/frontend/ @frontend-team @zhang-san
/src/components/ @ui-team
# 后端代码
/src/backend/ @backend-team
/src/api/ @api-team @li-si
# 基础设施
/infrastructure/ @devops-team
/.github/ @devops-team
# 特定文件类型
*.sql @database-team
*.tf @devops-team
package.json @tech-lead @frontend-team
# 安全相关
/src/auth/ @security-team @tech-lead
/src/crypto/ @security-teamCODEOWNERS 的效果：
- PR 修改了
/src/auth/时，@security-team自动被添加为 reviewer - 可以配置"必须由 CODEOWNERS 审批才能合并"
保护分支设置
在 GitHub/GitLab 中设置分支保护规则：
GitHub Branch Protection Rules
保护 main 分支的推荐配置：
✅ Require a pull request before merging
✅ Require approvals: 2
✅ Dismiss stale pull request approvals when new commits are pushed
✅ Require review from Code Owners
✅ Require status checks to pass before merging
✅ Require branches to be up to date before merging
✅ Status checks: CI/CD Pipeline, lint, test
✅ Require conversation resolution before merging
✅ Restrict who can push to matching branches: 仅 main 分支管理员
✅ Do not allow bypassing the above settingsGitLab Protected Branches
yaml
# .gitlab-ci.yml 中的相关配置
# 在 GitLab Web 界面 Settings > Repository > Protected Branches 配置：
main:
allowed_to_merge: Maintainers
allowed_to_push: No one
allowed_to_force_push: false
code_owner_approval_required: true贡献指南（CONTRIBUTING.md）
为项目创建贡献指南文档：
markdown
# 贡献指南
感谢你考虑为本项目做出贡献！
## 开发环境搭建
1. Fork 本仓库并克隆到本地
2. 安装依赖：`npm install`
3. 复制环境变量：`cp .env.example .env`
4. 启动开发服务器：`npm run dev`
## 分支规范
- 从 `develop` 分支切出功能分支
- 命名格式：`feature/<description>` 或 `fix/<description>`
## 提交规范
本项目使用 Conventional Commits 规范：
- `feat:` 新功能
- `fix:` Bug 修复
- `docs:` 文档更新
- ...
## Pull Request 流程
1. 确保分支基于最新的 `develop`
2. 确保所有测试通过：`npm test`
3. 确保代码符合规范：`npm run lint`
4. 创建 PR，填写描述模板
5. 等待至少 2 位成员 review 通过
## 代码规范
- 使用 ESLint + Prettier（已配置）
- 测试覆盖率不低于 80%
- 每个 PR 只包含一个功能或修复Issue 模板
.github/
└── ISSUE_TEMPLATE/
├── bug_report.md
└── feature_request.mdBug 报告模板：
markdown
---
name: Bug 报告
about: 创建 bug 报告以帮助我们改进
title: '[BUG] '
labels: bug
---
## Bug 描述
清晰简洁地描述 bug 是什么
## 复现步骤
1. 打开 '...'
2. 点击 '...'
3. 滚动到 '...'
4. 看到错误
## 期望行为
描述你期望发生什么
## 实际行为
描述实际发生了什么
## 截图
如果适用，添加截图来帮助解释问题
## 环境
- OS: [如 macOS 14.0]
- 浏览器: [如 Chrome 120]
- 版本: [如 v1.2.0]
## 额外背景
在此添加任何其他关于问题的背景信息总结
| 规范 | 工具/配置 |
|---|---|
| 提交信息 | commitlint + Husky |
| 分支命名 | pre-push 钩子 |
| Code Review | CODEOWNERS + 分支保护 |
| PR 流程 | PR 模板 + 自动化检查 |
| 文档 | CONTRIBUTING.md + Issue 模板 |
规范不在于多，而在于团队实际能执行。建议从最重要的规范开始（如提交信息规范、PR 流程），逐步完善其他内容。